Documentation comments are a method of reducing work and moving it from the documentation to the code itself in a way the first could easily generated. And as every programmer knows, documentation tends to be incomplete, out of date, wrong, or non-existent. Moving the documentation into the code makes them simply to maintain with the program or library.
Tools for generating documentation of API are comum today. They provide a simple method for programming and document in the same time. The documentation is near from API programmer, with the source code, and for the application programmer will be in a more readable and a easy to find method. They decrease the work of mainteining a documentation and building in a separate word processor.
This document is elaborated with the pourpose of specify a clear and easy documentation model for language D.
Each feature of source code is composed by a set of structures in language. For each structure we can provide a comment providing a description of it functionality, a explaination of a component, like parameters or modules or attaching a specific attribute containing information relationed. The comments are put, generally, before the specification of the feature.
See some examples below :
/**
* This function is a simple example
**/
int function(int x) {
return x;
}
/**
* author: Wolfrang Amadeus Mozart <wam@music.org>
*
* This class plays a sinfonie of Mozart. It can be used for learning music
* or for learning D documentation
**/
class sinfonie{
...
}
Documented comments use a variation of the standart documentation for D. They starts with the string '/**´ and finish with the string '**´:
/** This is a documented comment **/
typedef int normalvalue;
Alternatively a single line format can be used with the string '//*´:
//* This is a documented comment
typedef int normalvalue;
The documentation can span several lines. The extra blanks, tabulation and new lines are stripped:
/**
This comment will have
many lines
as needed
**/
If there are necessity of having more than one paragraph, you can add a blank line between :
/**
This is a paragraph
And this is another
**/
For clarity, the default form introduces a '*´ in the start of any line without the comments markers '/**´ and '**/´. The caracter is placed vertically aligned with the second caracter of the start comment string '/**´ and with caracter of the end comment string '**/´. The documentation is stripped after the caracter :
/**
* This comment will have
* many lines
* as needed.
*
* And this is the second paragraph.
**/
Aditional repeated chars at begin or at end are omited:
/***********************************
* The chars are omited
**/
The comment can have also a "tag" which specifies the documentation of a feature specific :
/**
* author: William Shakespeare <william@literature.net>
**/
module literature;
This tag specifies who is the author of the module. The module don´t have the its comment because the tag specify only the author. But you can combine sereral tags and the comment for making a more valuable comment :
/**
* author: William Shakespeare <william@literature.net>
* version: 1.0
*
* This module implements the logic for understanding the real interpretation of my ideas.
* It magically translate all ideas hidden from the simple reading and show to you.
**/
module literature;
The tags can be of two types :
Tags may be put before any declaration:
/** * author: William Shakespeare <william@literature.net> on 2002.03.04 05:06 * author: Wolfrang Amadeus Mozart <wam@music.org> on 2002.04.06 08:16 * version: 0.3 alpha * category: Example of Code Documentation * see: anotherexample, example, "D Programming Tutorial" * * This module is provided as example of documenting code with coddoc. It is * a example of how use the coments for generating documentation. **/ module docexample;
However in some cases the documentation can be put after the declarations. However the styles cannot be mixed. See the list of cases:
Tags in fields of a structure can be put after the declaration of field. If one fields is documented before the declaration, all fields must be too.
struct SDL_Color {
Uint8 r; //* The byte representing the red value for color
Uint8 g; //* The byte representing the green value for color
Uint8 b; //* The byte representing the blue value for color
Uint8 unused; //* This byte is reserved for future use
}
Alternatively simple procedures and class methods can be documented after its declaration. The documentation may start after the enclosing parenthesis:
int SendMessage(Protocol protocol, char[] message)
/**
* This function send a message througth the Protocol defined
* and return the time wasted during sending. If a problem happens
* a exception is throwed.
**/
{
...
}
All tags available for a function or a method are available in this form too.
The following are examples of author taglines, which may be used in documentation comments for module and types declarations:
/**
* author: William Shakespeare<william@literature.net>
* author: Dante Aglieri
* author: Jules Verne
**/
module literature;
The information in an author taglines could have the name, the quoted name, email or both but must follow the rule : name <email@someplace.com> . A documentation comment may contain more than one author tag. Alternatively, a single author paragraph may mention several authors:
/**
* author: Wolfrang Amadeus Mozart <wam@music.org>, Johanes Sebastian Bach <bach@music.org>,
* "Giuseppe Verdi", ravel@music.org
**/
class sinfonie {
...
}
Additionaly, the author tag can have a date complement specified by word "on". The date format used is the international ISO. See the example:
/**
* author: William Shakespeare <william@literature.net> on 2002.03.04 05:06
**/
class hamlet{
...
}
The following is an example of a license paragraph, which may be used in documentation comments for module declarations:
/**
* license:
* Copyright (c) 2001
* Pavel "EvilOne" Minayev
*
* Permission to use, copy, modify, distribute and sell this software
* and its documentation for any purpose is hereby granted without fee,
* provided that the above copyright notice appear in all copies and
* that both that copyright notice and this permission notice appear
* in supporting documentation. Author makes no representations about
* the suitability of this software for any purpose. It is provided
* "as is" without express or implied warranty.
**/
The license paragraph should contain all information relative at copyright, license and permission of use.
The following is an example of a version tagline, which may be used in documentation comments for type declarations:
/**
* version: 2.93.1 beta
**/
module imported;
The information in a version paragraph has two parts in internal structure. First is the version string. Last is optional and have the following values:
Default is stable. A documentation comment may contain at most one version tag.
The following are examples of see paragraphs, which may be used in any documentation comment to indicate a cross-reference to a type, method, constructor, field, URL, or any text:
/**
* see: c.stdio
* see: string
* see: string.equals
* see: threads.thread.wait(int)
* see: RandomAccessFile.RandomAccessFile(File)
* see: RandomAccessFile.RandomAccessFile(File, String)
* see: Character.MAX_RADIX
* see: D Spec
* see: "D Programming Tutorial"
**/
class implementation;
The character "." separates the name of a module of a class and the name of a class from the name of one of its fields, methods, or constructors. The order of searching is package, module, type, method. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name. URL follow the reduced html specification, with only href as property. Free form text need to be quoted. A documentation comment may contain more than one see tag. Alternatively, a single author paragraph may mention several authors:
/**
* see: c.stdio, file, stream, file.read
**/
int fscanf(string format, ...){
...
}
Specify in what version when the name was added to the API specification (if different from the implementation). It could be used in type in reference to module version or in method in reference to class version.
The following is an example of a since paragraph, which may be used in documentation comments for declarations of methods:
/**
* version: 0.3 alpha
*
* This class is on the third version
**/
class widgetfarm : farm {
/**
* since: 0.2
*
* This method is introduced in version 0.2 of this class
**/
void initwidgets {
...
}
}
The category tagline specify in what category the type or method is gruped. It could be used in classes to classify the properties, methods and members in a closed scope.
The following is an example of a category paragraph, which may be used in documentation comments for declarations of a functions:
/**
* category: Temperature handling routines
**/
int temperature {
...
}
Adds a example copied verbatim to documentation.
The following is an example of a example paragraph, which may be used in documentation comments for providing user examples:
/**
* example:
*
* // This ilustrate how to use a regexp to match a string
* RegExp myRegExp = new RegExp("[A-Za-z\b!]*");
* if (RegExp.Match("Hello World!")
* printf("Hello World!");
**/
class RegExp
{
...
}
Specify known issue in types, methods or routines.
The following is an example of a bug paragraph, which may be used in documentation comments for declarations of a functions:
/**
* bug: Windows 9x dont pass the correct memory used
**/
int memoryUsed {
...
}
Specify work to be done for implementing, optimizing or adequate types and methods.
The following is an example of a todo paragraph, which may be used in documentation comments for declarations of a class:
/**
* version: 1.0
* todo: modify to permit evaluate a string caracter by caracter
**/
class RegExp
{
...
}
Specify a text to build a glossary by subject. The glossary tag is a tagline but a documentation comment may contain more than one glossary tag.
The following is an example of a todo tagline, which may be used in documentation comments for declarations of a function:
/**
* glossary: Deleting files
* glossary: Erasing files
**/
void delelefile(string filename){
...
}
The following is an example of an resume tagline, which may be used for short describing a artifact:
/**
* resume: InterfaceDisconnect disconnects an IConnectionPoint interface.
*
* InterfaceDisconnect disconnects an IConnectionPoint interface connection
* that was previously made by the InterfaceConnect procedure.
* These procedures are wrappers for the ActiveX event-handling mechanism,
* the IConnectionPointContainer and IConnectionPoint interfaces.
**/
void InterfaceDisconnect(IUnknown Source, ClassIID IID);
The following are examples of parameters paragraphs, which may be used in documentation comments for method and constructor declarations:
/**
* file: the file to be searched
* pattern: the pattern to be matched during the search. The pattern could
* consist of a simple string or a regular expression.
* count: the max number of lines to brings for each match. O for all lines;
*
* Matches lines in a file which follow a pattern.
**/
char[] matchLines(File file, char[] pattern, int count);
The information in a parameter paragraph should consist of the name of the parameter followed by a short description.
A documentation comment may contain more than one parameter tag. The usual convention is that if any parameter paragraphs are present in a documentation comment, then there should be one parameter paragraph for each parameter of the method or constructor, and the parameters paragraphs should appear in the order in which the parameters are declared.
The following is an example of an import paragraph, which may be used in documentation comments for modules imports:
/**
* mymodule: module with auxiliary rotines
* c.stdio: needed for printf function
* stream: needed for reading and writing to files
**/
import mymodule, c.stdio, stream;
The information in an import paragraph should consist of the name of an module (which may be a simple name or a qualified name) followed by a short description of the need or dependency reason.
A documentation comment may contain more than one module tag.
The following is an example of an exception paragraph, which may be used in documentation comments for method and constructor declarations:
void verifyWidget(Widget widget)
{
if (!widget.flanged)
//* the widget does not have a flange, or its flange has size zero
throw new UnflangedWidgetError(´Missing flange´);
if (!widget.canUse)
/**
* the widget cannot be used. This happens because it was not
* initialized, it was not attached to a manager, it was not
* configured or it is hided.
**/
throw new UnusableWidgetError();
if (widget.InUse)
throw new LockWidgetError("Widget is already in use");
}
The comment in an exception paragraph is attached with the method which the error is throwed. For documenting the exception use a normal tag once a exception is a class.
The information in an exception paragraph should consist by a short description of the circumstances that cause the exception to be thrown. When a exception has no comment but have a message, the message is extracted as comment.
A method may contain more than one exception tag.
The following is an example of an return paragraph, which may be used in documentation comments for method and functions declarations:
byte cmpString(char[] str1, char[] str2)
{
if (str1 < str2)
/** condition : if the first string is smaller than second.
* return : a positive number
*/
return 1;
if (str1 == str2)
//* condition : if strings are equal
return = 0;
if (str1 == str2)
/** condition : if the first string is greater than second.
//* return: a negative number
return = -1;
}
The information in a return paragraph has a special internal structure:
A documentation comment for a function may contain at most one return tag.
Not all Attributes statements can be documented. There are no meaning in include documentation for the following tags:
Nevertheless the tool implementing documentation comments could include automatically the information and show or hide following user command.
The following attributes can be commented:
/**
* As of D 2.0, replaced by stream handling methods
* see: stream
**/
deprecated
{
char[] read(File f)
{
...
}
int write(File f, char[] buffer)
{
..
}
}
Tags will be included in documentation following the versioning scheme.
Each file generates one section in a docbook book.
The following are useful tips and conventions for writing descriptions in doc comments.
When referring to a method or constructor that has multiple forms, and you mean to refer to a specific form, use parentheses and argument types. For example, ArrayList has two add methods: add(Object) and add(int, Object).
The add(int, Object) method adds an item at a specified position in this arraylist.
However, if referring to both forms of the method, omit the parentheses altogether. It is misleading to include empty parentheses, because that would imply a particular form of the method. The intent here is to distinguish the general method from any of its particular forms. Include the word "method" to distinguish it as a method and not a field.
The add method enables you to insert items. (preferred) The add() method enables you to insert items. (avoid when you mean "all forms" of the add method)
In the interests of brevity this could be used. This holds especially in the initial summary and in parameter tag descriptions.
The description is in 3rd person declarative rather than 2nd person imperative.
Gets the label. (preferred) Get the label. (avoid)
A method implements an operation, so it usually starts with a verb phrase.
Gets the label of this button. (preferred) This method gets the label of this button. (avoid)
they can simply state the object. These API often describe things rather than actions or behaviors:
A button label. (preferred) This field is a button label. (avoid)
When referring to an object created from the current class is preferred use a more specific word. For example, the description of the getToolkit method should read as follows:
Gets the toolkit for this component. (preferred) Gets the toolkit for the component. (avoid)
The best API names are "self-documenting", meaning they tell you basically what the API does. If the doc comment merely repeats the API name in sentence form, it is not providing more information. For example, if method description uses only the words that appear in the method name, then it is adding nothing at all to what you could infer. The ideal comment goes beyond those words and should always reward you with some bit of information that was not immediately obvious from the API name.
The description below says nothing beyond what you know from reading the method name. The words "set", "tool", "tip", and "text" are simply repeated in a sentence. It's better avoid this form of documentate.
/** * Sets the tool tip text. * * text: The text of the tool tip. **/ public void setToolTipText(String text);
This description more completely defines what a tool tip is, in the larger context of registering and being displayed in response to the cursor. This form is preferred in comparison with the first.
/** * Registers the text to display in a tool tip. The text * displays when the cursor lingers over the component. * * text: The string to display. If the text is null, * the tool tip is turned off for this component. */ public void setToolTipText(String text);
Be clear when using the term common term.
Be aware that the common word as "field" can have many meanings and can confuse the reader.
Use "also known as" instead of "aka", use "that is" or "to be specific" instead of "i.e.", use "for example" instead of "e.g.", and use "in other words" or "namely" instead of "viz."