Syntax of doc comments

Format of a doc comment Tags Other files

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

Format of a doc comment

Directly comes from javadoc : A doc comment is written in HTML and must precede a class, field, constructor or method declaration. It is made up of two parts -- a description followed by block tags.
This definition also applies to non-object code (constants and functions).

Description

From javadoc specification : 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.
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

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 :
If a line terminator is found before the first period, the first sentence ends there. Otherwise, javadoc's definition applies.
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.

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 syntax of a tag is : @tagName value
By default, phpSimpleDoc accepts all tags, and recognizes a limited set of tag. 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).
Some tags are understood by phpSimpleDoc and are treated a special way :

@param, to indicate a function or method parameter
@return, to indicate what a function or method returns
@throw, to indicate exception thrown by a function or method
@deprecated (or @deprec), to indicate a deprecated element
@see (or @link), to indicate a link ; generates a line with "See also".
@todo, to indicate things to do
@author, to indicate the author of an element
@since, to indicate from when an element is available
@version, to indicate the version of an element

Inline tags

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

`@link` and `@linkplain` tags

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

<< User command files

Packages >>

Forum : Répondre à cet article