phpSimpleDoc > User guide > User directives

The directives to tell phpSimpleDoc what to do and how to do it are stored in "user directives files".
Each documented program correspond to one directives file.

The syntax of directives 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 in standard syntax, lines starting by a semicolon (;) are also ignored.

The directives files are organized in sections ; each section contains one or more directives.

Example

Let's look at the directives file used to generate phpSimpleDoc API documentation :

/********************************************************************************
  essentials
********************************************************************************/
[essential]
title = phpSimpleDoc
sourceDir = /path/to/phpsimpledoc/src
outputDir = /path/to/phpsimpledoc/output/phpsimpledoc
documentorType = default
topPackageName = phpsimpledoc
dontDoc = "
*/Zend*
*/.svn
*/z.*
*1.public-files*
*1.test-files*
*zz*
"

/********************************************************************************
  secondary
********************************************************************************/
[secondary]
unprocessedCopiedDirectories = doc-files
packageCommentFile = 1.package.html
overviewCommentFile = 1.overview.html

/********************************************************************************
  debug
********************************************************************************/
[debug]
active = yes
file = /tmp/phpsimpledoc.log

Here, we see that there are 3 sections (essentials, secondary and debug) ; each section contains directives, of the form :

key = value

If the directive can be expressed in a single line, the value mustn't be enclosed by quotes.
If several lines are needed for a directive, the value must be surrounded by double quotes (case of directive "dontDoc" in section "essential").

Complete list of directives

In page packages, we see that different ways to form package corresponds internally to different documentor implementation. Each implementation need different directives. The following table indicates the directives for 'default' and 'zendlike' documentors ('php' and 'flexible' documentor implementations are currently not documented).

When not specified, the option is available in both documentor types.

The bare minimum directives are 'sourceDir' and 'outputDir' of section 'essential'.

Note : all directives are compulsory, but if it has a default value, you can omit it in the .ini file.

'Since' designates the version of phpSimpleDoc since an option is available ; 'a' means 'alpha'.

When a directive can be 'yes' or 'no', true / false, or 0 / 1 also work, as in any the standard syntax of .ini file.

Section essential Necessary or most useful options.
Key	Comments	Since
title	Title of the program to document. Default value :"No Title"	1.0-a1
sourceDir	Absolute path to the top level directory of the code to document	1.0-a1
outputDir	Absolute path to the directory containing the generated documentation. PHP must have write access on this directory.	1.0-a1
documentorType	Indicates the type of documentor used to perform doc generation. Possible values : "default", "zendlike" Default value : "default"	1.0-a1
topPackageName	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 : "noname" For example, to generate doc for phpSimpleDoc, we have : topPackageName = phpsimpledoc In the generated documentation, the packages are named : phpsimpledoc, phpsimpledoc.app, phpsimpledoc.helpers etc.	1.0-a1
dontDoc	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 directories named "this_directory" and all their 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.*$/	1.0-a1
visibility	Indicates what class fields and methods should appear in the generated documentation. Possible values : "public", "protected", "private". Default value : "protected"	1.0-a1
Section secondary Settings concerning all generated pages
Key	Comments	Since
unprocessedCopiedDirectories	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 Possible values : a coma-separated list of strings. Default value : "doc-files" Example : unprocessedCopiedDirectories = dirName1, dirName2	1.0-a1
packageCommentFile	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).	1.0-a1
overviewCommentFile	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"	1.0-a1
Section syntaxes Indicates the associations between file extensions and syntaxes. As current implementation of phpSimpleDoc only handles php files, the only key is 'php'
Key	Comments	Since
php	Indicates to phpSimpleDoc which files should be considered as php files. Possible values : A coma-separated list of strings Default value : php, php3, php4, php5	1.0-a1
Section output Settings modifying the appearence of generated pages
Key	Comments	Since
frames	Indicates if the generated pages define a frameset or not. Possible values : yes or no Default value : yes 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.	1.0-a1
style	Useless for the moment as only one style is available. Possible values : "default" Default value : "default"	1.0-a1
Section statistics Settings concerning page "statistics" of generated documentation
Key	Comments	Since
active	Indicates if statistics about code should be computed Possible values : yes or no Default value : yes If this directive is "no", the other options of this section are not used	1.0-a1
countLines	Should number of lines be computed ? Possible values : yes or no Default value : yes This number includes comments and empty lines.	1.0-a1
countCodeLines	Should number of "code lines" be computed ? Possible values : yes or no Default value : yes This number does not include comments and empty lines. Slows the generation process.	1.0-a1
Section overviewPage Settings concerning the main page of the generated documentation
Key	Comments	Since
packageDepth	Depth of the package hierarchy displayed on the index page of the generated documentation. Possible values : must be an integer > 0 Default value : 3	1.0-a1
Section sourceCodePage Settings concerning pages containing a html representation of source code
Key	Comments	Since
active	Indicates if the documentor should generate pages containing html version of documented files' source code. Possible values : yes or no Default value : yes If this directive is "no", the other options of this section are not used	1.0-a1
echoLineNumbers	Should line numbers be echoed in the pages containing source code ? Possible values : yes or no Default value : yes	1.0-a1
Section allClassesPage Settings concerning the generated page containing the list of documented classes (all-classes.html)
Key	Comments	Since
displayPackages	Indicates if classes' packages should be listed in page all-classes.html. Possible values : yes or no Default value : yes	1.0-a2
skipPrefixInClassNames	Indicates if a prefix should be removed from class names to generate the list. Possible values : any string Default value : empty string For example, in Zend Framework, all class names start by "Zend_". Without this option, the alphabetical list of classes would only contain letter Z. Specifying skipPrefixInClassNames = Zend_ permits to build the alphabetical list	1.0-a2
Section methodListsPage Settings concerning pages listing class methods. Note : for version 1.0 alpha3, this setting is also used for other lists : class fields, class constants, constants, functions, global variables.
Key	Comments	Since
maxNbPerPage	If the documented program contains numerous methods, the generated page listing class methods is exploded in several pages. maxNbPerPage indicates the number of methods listed in each page. Possible values : must be an integer > 0 Default value : 100	1.0-a2
index-max-nb-per-line	When there are several pages listing class methods, an index with links to all these pages is displayed at top and bottom of each page. When pages are too numerous, these links must be displayed on several lines. index-max-nb-per-line indicates the maximal number of links that each line should contain. Possible values : must be an integer > 0 Default value : 25	1.0-a3
Section deprecatedPage Settings concerning page generating the list of deprecated elements (code elements containing tag @deprecated in their doc comment).
Key	Comments	Since
active	Indicates if deprecated page should be generated Possible values : yes or no Default value : yes	1.0-a3
Section todoPage Settings concerning page generating the list of todos (tags @todo in doc comments).
Key	Comments	Since
active	Indicates if todos page should be generated Possible values : yes or no Default value : yes	1.0-a3
Section log Settings concerning messages generated in a log file. Mainly useful for debug.
Key	Comments	Since
active	Indicates if logging is active Possible values : yes or no Default value : no If this directive is "no", the other options of this section are not used.	1.0-a2
file	File where debug messages will be written It can be an absolute or relative file name. If a relative file name is specified, il will be relative to the directory containing index.php (ex : /path/to/phpsimpledoc/src). PHP must have write access on this file. Possible values : absolute or relative file name Default value : /tmp/phpsimpledoc.log	1.0-a2
level	As phpSimpleDoc's log system uses internally Zend_Log, it has 8 log levels, from 0 (emergency) to 7 (debug). level indicates the maximum level to log. Possible values : EMERG, ALERT, CRIT, ERR, WARN, NOTICE, INFO or DEBUG Case insensitive Default value : WARN For example, with the default value (WARN), messages of level NOTICE, INFO and DEBUG won't be logged.	1.0-a3