Cause i didn't find a useful one, i try to define it for personal using. So some rules are strict.
These ideas come from javadoc and doxygen.
- markdown for the format of internal comment
- do not comment everywhere, you are doing coding not commenting
- @version can be saved into a stand alone file like VERSION if user forgets the version he downloaded in some distribution. Then if you get a release version, it is simple to find out the version of that file
/**
* @file filename.ext
* description...
*
* @author yarco <[email protected]>
* @since 2012/11/28
* @copyright BSD
*/
/**
* @class classname
* description...
*/
var v; //<! description...
- short version
//! short description
- long version (+ vim folding)
/** brief description {{{
*
* long description...
*
* @param type description...
* @return type description...
* @throws type description...
* @see somewhere
* @api public,deprecated
*/
/*}}}*/
// TODO: description...