The last email got muddled?
 
Simple typo - Copyright is spells wrong for one of the headings in that doc.
"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 :

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:

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

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

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."