Syntax of doc comments

- classes and interfaces
- class methods
- class fields
- class constants
- functions
- constants
- global variables

A doc comment must be placed immediately before the code element it documents.
A doc comment is a text between /** and */.

phpSimpledoc provides a strict implementation of javadoc specifications :
- If the two first asterisks are followed by other asterisks, they are removed from the comment.
- If the last asterisk is preceeded by other asterisks, they are removed from the comment.
- Within a doc comment, if a line starts by zero or more white spaces, followed by an asterisk, followed by one or more white spaces, they are removed from the comment.

Examples of valid doc comments :

/** A single line comment for a class constant */
const MY_CONST = 12;

/***********************************
  A comment with leading and trailing asterisks
*********************************/
const MY_CONST = 12;

/**
  * A comment with decorative asterisks
  * at the beginning of lines
  If you omit asterisks, the comment is still valid 
*/
const MY_CONST = 12;

Structure of a doc comment

Directly comes from javadoc : A doc comment is written in HTML (...) It is made up of two parts -- a description followed by block tags.

Again from javadoc : The first line that begins with an "@" character ends the description. There is only one description block per doc comment; you cannot continue the description following block tags.

So for example :

/**
  Here is the description
  It can go on several lines
  
  @tag tag stuff
*/
const MY_CONST = 12;

Description

The description stops at first tag encountered.
Written in html, the description is copied 'as is', with two exceptions :
- line breaks are converted to <br /> ; this poses a problem with <pre> tags, but this could be fixed (for the moment, using <code> instead gives correct result).
- Inline tags are converted.

First sentence

The description is divided in two parts :
- The first sentence
- The rest of the description

Javadoc's definition of first sentence is : This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag.
In practice, many comments have a first sentence followed by a line terminator, but without dot.
So the definition adopted in phpSimpleDoc is different from javadoc's : This definition is compatible with javadoc's, but the programmer can omit the period before the line break.

Here are 3 examples that give the same first sentence : «This is the first sentence »
- Example 1 :

This is the first sentence
Description continues on an other line.

- Example 2 :

This is the first sentence. Description continues on the same line.

- Example 3 :

This is the first sentence.
Description continues on an other line.

This first sentence is used in several parts of the generated documentation (lists). The rest of the description is only used in the detailed description of an element

Tags

Javadoc's definition :
Tags come in two types:
- Block tags - Can be placed only in the tag section that follows the main description. Block tags are of the form: @tag.
- Inline tags - Can be placed anywhere in the main description or in the comments for block tags. Inline tags are denoted by curly braces: {@tag}.

Block tags

They form the second part of a doc comment (the first part being the "description").
The general syntax of a block tag is :

@tagName value

Value is optional (depends on the tags).

A block tag can take several lines, as long as they don't start by a @ :

/**
  The description, before block tags
  
  @tag1 bla bla bla
        description of tag1 continues on this line
  @tag2 this line concerns tag2
*/

List of valid block tags

This definition differs from javadoc, which accepts a predefined set of tags.

If a tag is not recognized by phpSimpleDoc, it is just copied in the generated doc.
For example :

@myCustomTag Contents of the tag

will appear in the generated doc as :

MyCustomTag : Contents of the tag

(the first letter is upper cased).

Predefined block tags

Some tags are understood by phpSimpleDoc and are treated a special way.
In sections "Applies to", "All" means All documentable code elements : class methods, class fields, class constants, functions, constants, global variables.
In sections "Syntax", [...] means optional. If a compulsory element is not present, phpSimpleDoc reports a warning

Inline tags

They can appear anywhere in a description, or in a block tag value.

@link and @linkplain

To indicate a link to a URL or to an other documented element.
The only difference between @link and @linkplain is : in the generated pages, text coming from @link tag is placed beween <code> and </code>, and text coming from @linkplain is displayed in plain text.

The syntax differs from javadoc, and conforms to PhpDocumentor syntax
The syntax is : {@link target label} ; the label part is optional. ; the label part starts if the target is followed by a blank.
The syntax can take several forms ("[ ... ]" means optional) :

Syntax	Meaning and examples
{@link url[ label]}	Link to a URL {@link http://www.some.url.com} converted to : <a href='http://www.some.url.com'>http://www.some.url.com</a> {@link http://www.some.url.com this page} converted to : <a href='http://www.some.url.com'>this page</a>
{@link className[ label]}	Link to a class {@link Class1} converted to : <a href='path/to/class1.html'>Class1</a> {@link Class1 this class} converted to : <a href='path/to/class1.html'>this class</a>
{@link methodName()[ label]}	Link to a method of the same class {@link method1()} converted to : <a href='#method1'>method1()</a> {@link method1() this method} converted to : <a href='#method1'>this method</a>
{@link $fieldName[ label]}	Link to a field (= property) of the same class {@link $field1} converted to : <a href='#$method1'>$field1</a> {@link $field1 this field} converted to : <a href='#$method1'>this field</a>
{@link className::methodName()[ label]}	Link to a method of an other class {@link class1::method1()} converted to : <a href='path/to/class1.html#method1'>method1()</a> {@link method1() this method} converted to : <a href='path/to/class1.html#method1'>this method</a>
{@link className::$fieldName[ label]}	Link to a field of an other class {@link $field1} converted to : <a href='#$method1'>$field1</a> {@link $field1 this field} converted to : <a href='#$method1'>this field</a>

Note : class, method and field names must match php labels (for example defined in the constants page of php manual).

Other files

Default documentor only.
Apart from php files containing code to document, supplemetary files are processed by phpSimpleDoc :

• Overview comment file : the top level directory of source files can contain a file called by default overview.html. The contents of this file is included in the index page of the generated documentation.
• Package comment file ('default' documentor only) : each package can contain a file called by default package.html ; the contents of this file is used by phpSimpleDoc to retrieve the package description. Javadoc's package comments are not handled by phpSimpleDoc (for the moment).
• Unprocessed copied files : each directory can contain directories that will be copied as-is in the generated documentation. Javadoc introduced this feature with directory doc-files. It can be useful to include supplementary files, like images, and link to them from the from the doc comments.

References

Many definitions used in phpSimpleDoc come from Sun's How to Write Doc Comments for the Javadoc Tool and Javadoc reference page.

Some adaptations of java to php come from phpDocumentor.