How to use phpDoc to document software modules?
At YetAnotherCommunitySystem we have adopted phpDoc from the beginning as the tool of choice for software documentation. You can see the result at the scripts index.
Each time the set of reference scripts is rebuilt (scripts/build.php) the entire phpDoc documentation is rebuilt as well. To achieve this, every running script is parsed and analyzed.
Comments are filtered and combined in order to provide following items:
- the index page itself, at scripts/index.php
- the to-do list, at scripts/view.php/todo
- the authors page, at scripts/view.php/authors
- the testers page, at scripts/view.php/testers
- the license page, at scripts/view.php/licenses
The last four links are available at the top of the index page for scripts.
Compared to the legacy phpDoc, some keywords have been added to our own phpDoc module:
[*] [b]
[*] [b]
[*] [b]
[*] [b]
[*] [b]
[*] [b]
Of course, HTML tags can be used into script comments. However, the preferred solution to beautify text is to embed YACS codes when necessary.
Example from services/blog.php:
Also, each documentation page has links to browse or to fetch the script itsef. Here, browse means "read the target script in a pretty format", where fetch means "download and display the script itself".
For example, you can take a look at the back-end script used to support w.bloggar at the following address: scripts/view.php/services/blog.php. You will note the additional links under the main title to browse and to fetch the script.
[*] [b]
@todo[/b] to remind on things to do[*] [b]
@author[/b] and [b]@tester[/b] to reward contributors[*] [b]
@see[/b] to cross-link to the documentation page of another software module[*] [b]
@license[/b] to bind a software module to a license (e.g., LGPL)[*] [b]
@link[/b] to link software modules to any external page on the Internet[*] [b]
@reference[/b] to signal a script to be included in the reference setOf course, HTML tags can be used into script comments. However, the preferred solution to beautify text is to embed YACS codes when necessary.
Example from services/blog.php:
<?php
/**
* process remote blog calls
*
* @todo implement mt API - or should we?
*
* This script interfaces YACS with popular weblog client software.
*
* The support of the XML-RPC API in YACS is really straightforward.
* The main complexity is that different words are used for same things.
* Therefore, please keep in mind that metaWeblog' blogs are YACS sections.
*
...
*
* @author Bernard Paques [email]bernard.paques@bigfoot.com[/email]
* @reference
* @license http://www.gnu.org/copyleft/lesser.txt GNU Lesser General Public License
*
* @see services/blog_test.php
* @see services/configure.php
*
* @link http://www.xmlrpc.com/metaWeblogApi
* @link http://blogs.law.harvard.edu/tech/rss
* @link http://www.movabletype.org/docs/mtmanual_programmatic.html Movable Type User Manual: PROGRAMMATIC INTERFACES
*/
...
?>Also, each documentation page has links to browse or to fetch the script itsef. Here, browse means "read the target script in a pretty format", where fetch means "download and display the script itself".
For example, you can take a look at the back-end script used to support w.bloggar at the following address: scripts/view.php/services/blog.php. You will note the additional links under the main title to browse and to fetch the script.