Difference between revisions of "Documentation guidelines"
| (One intermediate revision by the same user not shown) | |||
| Line 38: | Line 38: | ||
*/ | */ | ||
| − | ===Method/ | + | ===Method/Constructor=== |
/** | /** | ||
* DOCUMENT (${user}) - insert description | * DOCUMENT (${user}) - insert description | ||
| Line 47: | Line 47: | ||
*/ | */ | ||
| − | === | + | === File === |
/** DOCUMENT (${user}) - insert description; @since ${date} ${time} */ | /** 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} */
