documon
Version:
A documentation system for mortals. Use with any language.
108 lines (76 loc) • 2.22 kB
Markdown
# Writing Comments Overview
Documon reads [JavaDoc](https://en.wikipedia.org/wiki/Javadoc) style blocks, which take the form of:
/**
* This is the traditional code-comment style
* block, with stars along the left edge.
* And this comment block is positioned
* immeditely above the method or property.
*
* @method myMethod
* @param {type} arg description
*/
function myMethod(arg){
var foo;
}
Where /** is used as a flag to designate the start of a documentation comment.
> NOTE: You can designate a different "start" and "end" string if your language uses non-C-like commenting. See the ["docBegin/End" options](more.options).
With Documon, you're not required to put stars down the left-hand side, you can do somehting like this:
/**
This is perfectly fine with Documon
For long, complicated comments with
HTML and examples may be a liitle
easier to write/read. Or if it's just
your preference
@method myMethod
@param {type} arg description
*/
function myMethod(arg){
var foo;
}
### Blocks
A single comment block is defined for each:
- variable
- function
- event
- class
The block contains a general top area where the __long description__ is written. THe long description is not required.
Tags appear after the long description. Tags are used to name, classify, categorize, link and generally describe the entity.
Tags can consume mulitple lines.
### Be Robust
Documon doesn't read or interpret your source code, and relies soley on @tags within comments, hence, one of the following tags MUST exist within each code block:
- @package / @namespace
- @class / @module
- @method
- @property
- @event
The tags listed above are essential for Documon to construct the documentation website.
### Example Property
/**
This is an example
@property foo
@type string
*/
var foo
or Documon's quick prop:
/**
@property {string} foo - description
*/
var foo
### Example method
/**
This function does something
@method foo
@param {type} bar - description
@return {type} description
*/
function foo(bar){
return bar + "hello";
}
### Example class
/**
This class does something
@class foo
*/
function foo(bar){
return bar + "hello";
}