A documentation model describes the format comments in the source code of a program must adhere to to be extractable by a documentation tool, which can then use the extracted information to create browsable or printable documentation, for instance in an html, pdf or word document format.
This document is created with the purpose of specifying a clear and easy documentation model for the programming language D.
Documentation comments are a method of reducing work by moving documentation from a separate document into the code itself in a way the documentation document could easily be generated. As every programmer knows, documentation tends to be incomplete, out of date, wrong, or non-existent. Moving the documentation into the code makes it easy to maintain with the program or library.
Tools for generating documentation of API's are commom today. They provide a simple method for programming and documenting at the same time. The documentation remains close to the source code for the API programmer, and for the application programmer will be in a more readable and easy to search format. They decrease the work of creating and maintaining documentation compared to writing it in a separate word processor. Most documentation generators will even be able to generate decent documentation from source code with no documentation comments in it at all, just from parsing the code itself. Adding good structured comments to the source code can greatly improve the value of the generated documentation however.
I would change or maybe even scrap this
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 standard documentation for D. They start 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;
To place a single line comment behind the source line, as is common, use '//<´:
typedef int normalvalue; //< This is a documented comment
The documentation can span several lines. The extra blanks, tabulation and new lines are stripped, just as with html:
/**
This comment will have
only as many lines
as needed
**/
If the documentation should be divided into more than one paragraph, you can add a blank line where you want to start a new paragraph:
/**
This is a paragraph
And this is another
**/
To allow the comment style often used by programmers where every line in the comment block starts with an asterisk (*) aligned with the first asterisk in the start comment tag, the first asterisk of the comment lines are stripped if every comment line starts with an asterisk as the first non-whitespace character:
/**
* This comment will have
* only as many lines
* as needed.
*
* And this is the second paragraph.
**/
Aditional repeated chars after the start tag or before the end tag are omited:
/***********************************
* The repeated chars are omited
***********************************/
As you will see in the next section I propose a change in the standard that is pretty big. I say we change the way tags are described to a method that is essentially xml compliant. There are a few reasons for this:
The process of extracting and translating the comments would then be:
The comment can also have embedded xml tags which specify the documentation of specific properties:
/**
* <author>William Shakespeare</author>
**/
module literature;
This tag specifies the author of the module. You can combine sereral tags and text in the comment:
/**
* <author>William Shakespeare</author>
* <version>1.0</version>
*
* This module implements the logic for understanding the real
* interpretation of my ideas. It magically translates all ideas
* hidden from the simple reading and shows them to you.
**/
module literature;
I would scrap this, because with xml tags it is no longer necessary to make any distinction between different types of tags.
The tags can be of two types :
Documentation comments may precede the declaration:
/**
* <author>William Shakespeare</author>
* <author>Wolfgang Amadeus Mozart</author>
* <version>0.3</version>
* <category>Example of Code Documentation</category>
* <see>D Programming Tutorial</see>
*
* This module is provided as an example of documenting code with coddoc.
* It is an example of using the comments for generating documentation.
**/
module docexample;
It is also allowed to place documentation comments after the declaration using the special start tag ´//<´. These comments may only span one line however. Both forms may be mixed freely.
This is an example of a struct with documentation comments. Both forms are used:
struct SDL_Color {
//* The byte representing the red value for color
Uint8 r;
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 author tag specifies the author or one of the authors of a module. It has the following optional properties:
| Property | Description |
|---|---|
| nati | Specifies the authors nationality |
| lang | Specifies the authors native language |
| born | Specifies the authors birthdate |
| work | Specifies the authors occupation at the time of writing |
| Specifies an email address where the author can be reached | |
| date | specifies the date the author started or joined in the development |
| site | specifies an url to the authors website |
The following are examples of author tags, which may be used in documentation comments for module and types declarations:
/**
* <author mail="william@literature.net" on="2002.03.04 05:06">William Shakespeare</author>
* <author mail="wam@music.org" lang="german">Wolfgang Amadeus Mozart</author>
* <author site="www.dante.literature.net">Dante Aglieri</author>
* <author>Jonathan Doe</author>
* <author work="compiler walter">Walter Bright</author>
**/
module literature;
Tag and property contents are generally not checked for syntax. This means one could enter an invalid e-mail address for example. Also data formats in general are not fixed. The contents of tags and properties are displayed in the documentation as the author entered them.
Multple authors in one tag is not ok with xml
The information in an author tagline could have the name, the quoted name, email or both but must follow the format: name <email>. A documentation comment may contain more than one author tag. Alternatively, a single author tagline may mention several authors, separated by commas:
/**
* author: Wolfrang Amadeus Mozart <wam@music.org>, Johanes Sebastian Bach <bach@music.org>,
* "Giuseppe Verdi", ravel@music.org
**/
class sinfonie {
...
}
This can be scrapped, because all properties are described above
Additionaly, the author tag can have a date complement specified by the 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 copyright tag may be used to describe the copyright holder information for the module, class or method
| Property | Description |
|---|---|
| date | The creation date of the document |
/**
* <copyright date="2001">Pavel "EvilOne" Minayev</copyright>
*
* This module provides a class library for windows programming.
* It contains controls necessary for creating windowed applications
* such as edit controls, list controls, menus, status bars and
* many other controls. It is also possible to derive your own
* custom controls.
**/
module wind;
The license paragraph should contain all information applicable to licensing terms and permission of use.
| Property | Description |
|---|---|
| site | url of website containing the licence or extra information pertaining the licence |
The following is an example of a license paragraph, which may be used in documentation comments for module declarations:
/**
* <licence site="http://www.gnu.org/copyleft/gpl.html">
* 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.
* </licence>
*
* This module provides a class library for windows programming.
* It contains controls necessary for creating windowed applications
* such as edit controls, list controls, menus, status bars and
* many other controls. It is also possible to derive your own
* custom controls.
**/
module wind;
Describes version information.
| Property | Description |
|---|---|
| status | Status of the release, such as alpha, beta, prerelease, candidate, unstable, stable, final |
The following is an example of a version tag, which may be used in documentation comments for type declarations:
/**
* <version status="beta">2.93.1</version>
**/
module imported;
I don't think it is necessary to enforce the different values for status.
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:
A documentation comment may contain at most one version tag.
References an alternative source of information.
| Property | Description |
|---|---|
| href | A url referencing the document |
The following are examples of see tags, which may be used in any documentation comment to indicate a cross-reference to a type, method, constructor, field, external document, or any text:
/**
* <see>c.stdio</see>
* <see>string</see>
* <see>string.equals</see>
* <see>threads.thread.wait(int)</see>
* <see>RandomAccessFile.RandomAccessFile(File)</see>
* <see>RandomAccessFile.RandomAccessFile(File, String)</see>
* <see>Character.MAX_RADIX</see>
* <see href="spec.html">D Spec</see>
* <see>D Programming Tutorial</see>
**/
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.
Doxygen parses the comments, and every word that matches the name of a type, function or global variable is automatically turned into a link to the part of the documentation describing that element. I found that very useful and it may be wise to require this in the standard.
Specify in what version the element was added to the API specification (if different from the implementation). It could be used in a type in reference to the previous module version, or in a method in reference to the previous class version.
The following is an example of a since tag, which may be used in documentation comments for declarations of methods:
/**
* <version status="alpha">0.3</version>
*
* This class is on the third version
**/
class widgetfarm : farm {
/**
* <since>0.2</since>
*
* This method is introduced in version 0.2 of this class
**/
void initwidgets {
...
}
}
The category tagline specifies in what category the type or method is grouped. 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 tag, which may be used in documentation comments for declarations of functions:
/**
* <category>Temperature handling routines</category>
**/
int temperature {
...
}
Adds an example copied verbatim to the documentation.
The following is an example tag, 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!");
* </example>
**/
class RegExp
{
...
}
The formatting in the documentation remains exactly the same as it is in the source code. No whitespace is removed. A non-proportional font, such as courier is used for the examples, so simple ASCII drawings will survive the translation intact.
Specifies known issues in types, methods or routines.
| Property | Description |
|---|---|
| severity | Severity of the bug, such as low, medium, high, severe, critical |
The following is an example of a bug tagline, which may be used in documentation comments for declarations of functions or classes:
/**
* <bug severity="high">Windows 9x does not pass the correct memory used</bug>
**/
int memoryUsed {
...
}
Specifies work to be done, such as implementing, optimizing or documenting certain 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</version>
* <todo>Modify to permit evaluation of a string caracter by caracter</todo>
**/
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>
* <glossary>Erasing files</glossary>
**/
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.</resume>
*
* 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);
How about naming this summary?
Describe parameter information.
| Property | Description |
|---|---|
| name | Name of the parameter described (mandatory) |
The following are examples of param tags, which may be used in documentation comments for method and constructor declarations:
/**
* <param name="file">The file to be searched</param>
* <param name="pattern">The pattern to be matched during the search.
* The pattern could consist of a simple string or a regular expression.</param>
* <param name="count">The max number of lines to brings for each
* match. O for all lines;</param>
*
* 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.
Because name is a property of the param tag, the order of the param tags is not important.
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.
I say replace this
The following is an example of an import paragraph, which may be used in documentation comments for modules imports:
/**
* mymodule: module with auxiliary routines
* 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.
With this:
/**
* Auxiliary routines
**/
import mymodule;
/**
* Needed for printf function
**/
import c.stdio;
/**
* Needed for reading and writing to files
**/
import stream;
Or this:
import mymodule; //< Auxiliary routines
import c.stdio; //< Needed for printf function
import stream; //< Needed for reading and writing to files
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 an exception is a class.
The information in an exception paragraph should consist of a short description of the circumstances that cause the exception to be thrown. When an exception has no comment but has a message, the message is extracted as comment.
Do you mean that if an exception is thrown with a literal string as an argument that argument is used for the comment? so throw new LockWidgetError("Widget is already in use"); would give "Widget is already in use" as the message? I don't know if this is possible, because it might be mixed with parameters: throw new LockWidgetError("Widget %d is already in use", widgetno);
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:
I don't know about all this...Seems really cool, but maybe also really complex for the documentation tool?
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</see>
**/
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 specifying data such as dates and times use accepted standards such as ISO:
module greataddon; //< should be ready 2002.12.31 00:00:00.
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. * * <param name="text">The text of the tool tip.</param> **/ 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. * * <param name="text">The string to display. If the text is null, * the tool tip is turned off for this component.</param> */ 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."