Documentation guidelines
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} */
