Code documentation - How about using xml? (page 5) - D Programming Language Discussion Forum

August 22, 2002
Re: Code documentation v2
Posted by anderson
in reply to Juarez Rudsatz
Permalink
anderson
Posted in reply to Juarez Rudsatz
Permalink
Source code documentation with coddocTag copyrigth ??? Spelling

"Juarez Rudsatz" <juarez@nowhere.com> wrote in message
news:Xns9271CD52FD128juarezcorreiocom@63.105.9.61...
Hi all!

    I am sending the second version of this especification.
    Is not concluded yet.
    Let's comment, criticize, speculate, think, talk ....

Juarez Rudsatz

Juarez Rudsatz <juarez@correio.com> wrote in news:Xns9249C9E0B98EEjuarezcom@63.105.9.61:

> Hi all!
>
>          I am sending a very preliminary version of a specification
>          for
> implementing a sintax for document source files using the /* */
> comments.
>          It's a preliminary version and contain, certainly, design and
> language errors.
>          Please read the attached html file and send your comments.
>




Abstract
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.
Introduction
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.
How source code is documented
Each feature of source code is composed by a set of language structures. For
each structure is attached a comment providing a description of it
functionality, a explaination of a component or classifying its atributes.
See some examples below :
A function being documented:
 /**
  * This function is a simple example
 **/
 int function(int x) {
  return x;
 }

A class being documented
 /**
  * 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{
 ...
 }

How tags are parsed
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;

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
 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
  * many lines
  * as needed.
  *
  * And this is the second paragraph.
 **/

Aditional repeated chars at begin or at end are omited:
 /***********************************
  * The repeated chars are omited
 ***********************************/

The comment can have also a "tag" which specifies the documentation of an
specific atribute:
 /**
  * author: William Shakespeare <william@literature.net>
 **/
 module literature;

The former tag specifies the author of the module. You can combine sereral
tags and text in the 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;

Types of Tags
The tags can be of two types :
Taglines are tags described in one line. The tag end at the newline
caracter. As example there are the version, since, category and glossary
tags.
Tag paragraphs are tages described in one or more lines. The tag end is at
the next tag or the end of comment.
Position of Tags
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;

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:
 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
 }

Especific tags
Tag author
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;

Tag copyrigth
The copyright tag may be used to describe the copyright holder information
for the module, class or method
 /**
  * copyright: Pavel "EvilOne" Minayev (c) 2001-2002
  *
  * 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;

Tag license
The following is an example of a license paragraph, which may be used in
documentation comments for module declarations:
 /**
  * license:
  * 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 applicable to licensing
terms and permission of use.
Tag version
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;

Tag since
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 {
   ...
  }
 }

Tag see
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 Language Specification" at
http://www.digitalmars.com/d/spec.html
  * 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.
Tag category
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 {
 ...
 }

Tag example
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
 {
 ...
 }

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.
Tag bug
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: Severity High. Windows 9x dont pass the correct memory used
 **/
 int memoryUsed {
 ...
 }

Tag todo
Specify work to be done, such as implementing, optimizing or 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
  * todo: modify to permit evaluate a string caracter by caracter
 **/
 class RegExp
 {
 ...
 }

Tag glossary
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){
 ...
 }

Tag summary
The following is an example of an summary tagline, which may be used for
short describing a artifact:
 /**
  * summary: 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);

Generic tags
Tags for parameters
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 but this is not
mandatory.
Tags for imports
The following is an example of an import paragraph, which may be used in
documentation comments for modules imports:
 /**
  * Auxiliary routines
 **/
 import mymodule;

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.
Additionaly, modules can be documented together simply by specifying the
name of module contained in the colon list.
 /**
  * mymodule: Auxiliary rotines
  * c.stdio: needed for printf function
  * stream: needed for reading and writing to files
 **/
 import mymodule, c.stdio, stream;

Tags for exceptions
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 widget is
already used
 }

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.
Tags for return values
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)
   /** if the first string is smaller than second.
    * return a positive number
    */
   return 1;
  if (str1 == str2)
   //* if strings are equal return zero
   return = 0;
  if (str1 == str2)
   /** if the first string is greater than second.
   //* return a negative number
   return = -1;
 }

Tags for Attributes
Not all Attributes statements can be documented. There are no meaning in
include documentation for the following tags:
private
protected
public
export
Nevertheless the tool implementing documentation comments could include
automatically the information and show or hide following user command.
The following attributes can be commented:
deprecated
override
abstract
const
final
static
 /**
  * As of D 2.0, replaced by stream handling methods
  * see: stream
 **/
 deprecated
 {
  char[] read(File f)
  {
  ...
  }

  int write(File f, char[] buffer)
  {
  ..
  }
 }

Tags for Contracts
Contracts are a breakthrough technique to reduce the programming effort for
large projects. Contracts are the concept of preconditions, postconditions,
errors, and invariants. Contracts form part of the specification for a
program, moving it from the documentation to the code itself.
The comment in an assert contract is attached with the method which the
contract is verified. For documenting the contract use a normal tag
explaining the reason os such restriction. Assert contract without a
documentation comment is not added in the documentation.
Not all contracts can be documented. Following tags are not documented:
out contracts in methods
unittest contracts
There are no meaning in include documentation for these contracts because
they are commonly used for verification of accuracy of results and for
determining if the code is working properly.
The following contracts can be commented:
in contracts in methods
class invariants
In Contracts
The following is an example of documentation of an assert contract in a
function in contract:
 int div(int x , int y)
 in
 {
  //* The divisor cannot be zero.
  assert(y != 0);
 }
 body
 {
  return x / y;
 }

Class Invariants
The following is an example of documentation of an assert contract in a
class invariant:
 class Date
 {
 int day;
 int hour;

 invariant()
 {
  //* The day must be between 1 and 31
  assert(1 <= day && day <= 31);
  //* The hour must be between 0 and 23
  assert(0 <= hour && hour < 24);
 }

Tags and versioning
Tags will be included in documentation following the versioning scheme.
Tags and inheritance
Inherited classes and structs will inherit tags for all methods defined in
ancestral which are not modified by an new documentation comment.
Compilaton process
The compiler will parse each file and generate a new file containing the
comments stripped from source and all information about the feature being
documented.
The format of all files generated is the docboock format. Each source file
generates one new file containing a section in a docbook book. The document
must be also a valid XML 1.0 document.
Users could use a docbook processor for generate documentation in html
format, text format, pdf format or any available format.
Users can also write their own preprocessor since the output of code
documentation will be a simple xml document.
Sugested comments for statements
Tags in simple types
Tags in simple procedures
Tags in functions
Tags in structures
Tags in classes
Best practices
A Style Guide
The following are useful tips and conventions for writing descriptions in
doc comments.
When specifying data use formal and standard notation
When specifying data such as dates and times use accepted standards such as
ISO. This way foreign readers will not be confused by month, day positions.
 module greataddon;  //< should be ready 2002.12.31 00:00:00.

Omit parentheses for the general form of methods and constructors
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)

Okay to use phrases instead of complete sentences
In the interests of brevity this could be used. This holds especially in the
initial summary and in parameter tag descriptions.
Use 3rd person (descriptive) not 2nd person (prescriptive).
The description is in 3rd person declarative rather than 2nd person
imperative.
 Gets the label.   (preferred)
 Get the label.   (avoid)

Method descriptions begin with a verb phrase.
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)

Class/interface/field descriptions can omit the subject.
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)

Use "this" instead of "the"
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)

Add description beyond the API name.
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.
Avoid Latin
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."
Forums
