Writing Doc Comments

This section covers:

• Format of jGrouseDoc comment
• Comment names
• Inherited descriptions
• Scope Control
• Links

Format of jGrouseDoc comment

jGrouseDoc extracts from source files sections that start with /** and end with */. Within these sections the tool would expect to find general description of item being documented followed by one of comment tags which could be optionally followed by several comment attributes.

Comment tags specify what kind of element is being documented (function, class, file, etc) and comment attributes provide additional information about the element (parameters, authors, return types, etc).

The code with jGrouseDoc comments could look like this:

/**
Adds two numbers together. <b>Sample only.</b>
Could be used as mixin to {@link com.foo.SomeClass SomeClass}
@function {public static int} ?
@param {int} first - first number
@param {optional int} second - second number
@returns sum of two numbers
@author den
@since 0.9
@version 1.3
@throws InvalidArgumentException when sum of two numbers greater than 100
*/
function add(first, second)
{
  var r = first + second;
  if (r > 100)
  {
    throw new InvalidArgumentException("NumberTooBig");
  }
  return r;
}

When jGrouseDoc is applied to such code, it would produce documentation that conceptually looks like this:

This simple example shows the following important parts of typical jGrouseDoc comment:

• jGrouseDoc parses comments that start with /** and end with */
• Multi-line detailed description (the part with "Add two numbers...")
• A section containing the comment tag (in this case - @function) followed by optional modifiers and return type enclosed in {} (in this case - {public static int}), followed by comment name (in this case - name placeholder ?) and optional summary description of the described item (not present in this case)
• optional comment attributes (@param, @author, etc)
• in-line references to other elements using the {@link... } tag

If the summary description is not specified, then jGrouseDoc would use the first sentence of the detailed description as a summary. The system makes a bold assumption that all sentences end with dot, so in this example the system would use "Adds two numbers together." as summary for this comment.

Comment names

As you can see from the example, the comment itself does not contain the name of the function that is being documented. Instead, the @function tag contains a name placeholder ?, which instructs jGrouseDoc to extract the first identifier from the code below the comment and use that identifier.

Of course, there are lots of cases when you cannot rely on the first available identifier being the one you would want to document. In this case it is possible to specify the name explicitly:

/**
...
@function {public static int} add
...
*/

In certain cases you might want to specify full element name, like com.foo.Bar. Typically you would specify full name for classes, interfaces, namespaces and other logical containers. For elements that are not containers (functions, variables, etc) there is usually no need to specify the full name, since the scope is known. For example, when describing a class with two members, your documentation could look like this:

/**
@class com.foo.MyClass
*/
....

/**
@var {String} myStringMember
*/

/**
@function {Boolean} testSomething
*/

In this case jGrouseDoc would assume that myStringMember and testSomething have fully-qualified names of com.foo.mar.MyClass.myStringMember and com.foo.bar.MyClass.testSomething.

A notable exception in this case is when you want to describe something out of default scope, like a mixin. For example, if you want to add a member to standard Array, you can specify name as Array.myNewMember:

/**
@function Array.myNewMember
*/

Note the tool does not extract full names from the code, so if you would prefer to use the ? placeholder in such case, you would need to put in your comment something like

/**
@function Array.?
*/
function myNewMember()
{
...
}

Whenever the tool encounters a declaration with a name that does not appear to be fully-qualified and does not appear to be a member of a class, namespace, etc, the tool would assume that the declaration belongs to GLOBAL namespace. Modern libraries tend to avoid putting code into global namespace, so the tool would issue a warning regarding such occurrence. Note that those warnings could be easily suppressed - see the Advanced Configuration section

Inherited descriptions

When documenting members of a subclass/subinterface it could be advantageous to be able to specify that certain member is overridden and be able to copy the description from the superclass' member definition. This is done using the @inheritdesc tag:

/**
@function subclassMember
@inheritdesc
*/

Scope Control

The previous examples show that whenever the tool encounters a non-fully-qualified name, it puts it into the scope of current logical container (class, interface, etc).

There could be cases when all the members of the same class, namespace, etc are not grouped together or could be distributed between several files. In order to address that problem you can use scope-control tags @scope and @end.

Links

The tool would automatically place links referencing other documented elements (classes, functions, etc). Links would appear in several places

• Declarations (return types, argument types, field types)
• "See Also" sections generated from @see tags
• In-line text generated from {@link} tags
• Exception names generated from @throws tags
• Generated references to superclasses and implemented interfaces
• Generated references to immediate subclasses/subinterfaces and implementing classes (for interfaces)
• Summary tables listing modules, classes, functions, variables, etc
• Generated references to inherited/implemented methods and variables
• The index (where applicable)

See the documentation for {@link} tag for details.