Documentation guideline

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((%%FIXME%% is high priority, TODO is normal priority, and XXX is normal priority too)) tag)
  * What is really important to be done. (%%FIXME%% tag)

JavaDoc

<note important>Javadoc: http://www.arsini.org/javadoc/ (user: developer / password: developer)</note>

<note>To generate a new version of the JavaDoc website please execute S:\ARSIN_V01\javadoc\gen_javadoc.bat. Afterwards copy the content of folder S:\ARSIN_V01\javadoc\website manually (via ftp) to /webserver/www.arsini.org/apache/javadoc.</note>

Eclipse provides you with functions to add comment templates to your classes/methods/variables. If you are within the curly brackets {} of the element to be commented, either press ALT+SHIFT+J, or open the context menu (right mouse button) and goto "Source > Generate Element Content". In the following, the templates added to eclipse are listed:

<note> In projects BW, DecisionUnitInterface, DecisionUnitMasonInspectors, decisionUnits, and Sim these comment structure are checked in into the eclipse project settings! </note>

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

Field

/** DOCUMENT (${user}) - insert description; @since ${date} ${time} */

Webresouces

 * http://en.wikipedia.org/wiki/Javadoc
 * http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

{{tag>documentation guidelines Java}}
{{backlinks>.}}