To document a new program, you need to create user command file (generally a
.ini file).
The syntax of command files is the
syntax of PHP ini files, with one difference : C-like comments (
// and
/* */) are admitted ; this permits to comment multiple lines at once. As usual, lines starting by a semicolon (;) are also ignored.
The different documentor implementations need different options to run ; the following table indicates the directives for 'default' and 'zendlike' documentors ('php' documentor not currently documented). When not specified, the option is available in both documentors.
Note : an option can be compulsory, but if it has a default value, you don't need to worry about it.
For a start, the only necessary options are 'sourceDir' and 'outputDir' of section 'essential'.
Section "essential"
Necessary or most useful options.
|
| Key | Compulsory or Optional | Comments |
|---|
| title |
Compulsory |
Title of the program to document.
Default value : set to No Title if absent.
|
| sourceDir |
Compulsory |
Absolute path to the top level directory of the code to document
|
| outputDir |
Compulsory |
Absolute path to the directory containing the generated documentation.
PHP must have write access on this directory.
|
| documentorType |
Compulsory |
Indicates the type of documentor used to perform doc generation.
Possible values : default, zendlike, php
Default value : set to default if absent.
|
| topPackageName |
Compulsory |
Only for 'default' documentor
Used to name the packages in the generated documentation
Possible values : any string without white spaces or accentuated characters.
Default value : set to noname if absent
For example, to generate doc for phpSimpleDoc, I have :
topPackageName = phpsimpledoc
In the generated documentation, the packages are named :
phpsimpledoc,
phpsimpledoc.app,
phpsimpledoc.helpers
etc.
|
| dontDoc |
Optional |
A set of patterns ; files in the source directory matching these patterns won't be documented.
Default value : empty string
The syntax is :
dontDoc = "
pattern1
pattern2
...
(put one pattern per line)
"
Examples of patterns :
*.xml (don't document files ending by ".xml").
*/this_directory* (don't document directory named "this directory" and all its files and subdirs).
Patterns' syntax is "simplfied PCRE" : to be converted to the usual PCRE syntax,
/^ is prepended
$/ is appended
. are replaced by \.
/ are replaced by \/
* are replaced by .*
For example, the pattern :
*/aDirectoryToSkip*
is replaced by :
/^.*\/aDirectoryToSkip.*$/
|
| visibility |
Optional |
Indicates what class fields and methods should appear in the generated documentation.
Possible values : public, protected, private.
Default value : protected
|
Section "secondary"
Settings concerning all generated pages, in general useless
|
| Key | Compulsory or Optional | Comments |
|---|
| unprocessedCopiedDirectories |
optional |
List of directory names that will be copied in the output directory without modifications
Equivalent of javadoc's doc-files.
To specify several directories, separate the directory names by comas
|
| packageCommentFile |
Compulsory |
Only for 'default' documentor
Name of the file to look to retrieve the comment of a package.
Default value : package.html
Try to avoid using hidden file names (like .package.html).
|
| overviewCommentFile |
Compulsory |
Name of the file to look to retrieve the comment that will be included on the index page of the generated documentation.
Default value : overview.html
|
Section "output"
Settings modifying the appearence of generated pages
|
| Key | Compulsory or Optional | Comments |
|---|
| frames |
Optional |
Possible values : yes or no
(true / false, or 0 / 1 also work, as in any .ini file)
Default value : yes
Indicates if the generated pages define a frameset or not.
Note : Documentations without frameset have a left column containing the class names. This can be useful for small APIs, but it becomes very heavy for large APIs.
|
| style |
Compulsory |
Possible values : default
Default value : default
Useless for the moment as only one style is available.
|
Section "statistics"
Settings concerning page "statistics" of generated documentation
|
| Key | Compulsory or Optional | Comments |
|---|
| countLines |
Compulsory |
Possible values : yes or no
Default value : yes
Should number of lines be computed ?
This number includes comments and empty lines.
|
| countCodeLines |
Compulsory |
Possible values : yes or no
Default value : yes
Should number of "code lines" be computed ?
This number does not include comments and empty lines.
Slows the generation process.
|
Section "overviewPage"
Settings concerning the main page of the generated documentation
|
| Key | Compulsory or Optional | Comments |
|---|
| packageDepth |
Compulsory |
Possible values : must be an integer > 0
Default value : 3
Depth of the package hierarchy displayed on the index page of the generated documentation.
|
Section "sourceCodePage"
Settings concerning pages containing a html representation of source code
|
| Key | Compulsory or Optional | Comments |
|---|
| active |
Compulsory |
Possible values : yes or no
Default value : yes
Indicate if the documentor should generate pages containing html version of documented files' source code.
|
| echoLineNumbers |
Compulsory |
Possible values : yes or no
Default value : yes
Should line numbers be echoed in the pages containing source code ?
|
