Difference between revisions of "Documentation guidelines"
| (2 intermediate revisions by the same user not shown) | |||
| Line 21: | Line 21: | ||
===File=== | ===File=== | ||
| − | + | /** | |
* CHANGELOG | * CHANGELOG | ||
* | * | ||
| Line 37: | Line 37: | ||
* ${tags} | * ${tags} | ||
*/ | */ | ||
| + | |||
| + | ===Method/Constructor=== | ||
| + | /** | ||
| + | * DOCUMENT (${user}) - insert description | ||
| + | * | ||
| + | * @since ${date} ${time} | ||
| + | * | ||
| + | * ${tags} | ||
| + | */ | ||
| + | |||
| + | === File === | ||
| + | /** DOCUMENT (${user}) - insert description; @since ${date} ${time} */ | ||
Latest revision as of 15:15, 18 December 2012
Contents
What to Document
- Who wrote the code, so proper credit can be given when credit is due, and so others know who to ask for advice when adapting it in the future;
- When it was written;
- What the code accomplishes;
- Where the code fits into the overall architecture of the application;
- How the code is used, providing an example if possible, or at least an explanation of the parameters the code expects to use and variables it alters;
- Why design decisions were made or another existing routine was not used.
Additionally
- What still needs to be done; (TODO) tag)
- What is really important to be done. (FIXME tag)
JavaDoc
Javadoc: http://www.arsini.org/javadoc/ (user: developer / password: developer)
To generate a new version of the JavaDoc website please execute S:\ARSIN_V01\javadoc\gen_javadoc.bat.
File
/**
* CHANGELOG
*
* ${date} ${user} - File created
*
*/
Class/Enum/Interface
/**
* DOCUMENT (${user}) - insert description
*
* @author ${user}
* ${date}, ${time}
*
* ${tags}
*/
Method/Constructor
/**
* DOCUMENT (${user}) - insert description
*
* @since ${date} ${time}
*
* ${tags}
*/
File
/** DOCUMENT (${user}) - insert description; @since ${date} ${time} */
