Documentation: scripts/phpdoc.php

class PhpDoc - Parse PHP scripts to build the on-line documentation

This class is derived from previous work originally coming from the Java world, by which developers have found a mean to auto-document their files.

Some PHP developers have selected similar rules to achieve the same result with scripts, and I must admit that this (very simple) solution may deliver sensible results with ease.

Are you able to produce or to alter some PHP code?
Would you like to achieve a simple view of all these files?
What about reading some pretty HTML before browsing the code itself?
Oh yes! Maybe you would like to link things together (e.g. 'see also this script...')
Do you want to locate easily scripts on your todo list?
Are you tracking software contributors to better reward them?
Are you dreaming of locating some information through full-text search?

If you have answered yes to a couple of these questions, then you'd better read the end of this page.

Documentation blocks

The documentation process begins with the most basic element of phpDoc: a documentation block. A basic documentation block looks like this:

/**
 *
 */

A documentation block is an extended C++-style PHP comment that begins with "/**" and has an "*" at the beginning of every line. documentation blocks precede the element they are documenting. To document function "foo()", type:

/**
* Defies imagination, extends boundaries and saves the world ...all before breakfast!
 */
function foo()
{
}

A documentation block contains three basic segments in this order:

short description
long description
tags

The short description is the very first text line of the documentation block. The long description continues for as many lines as desired and may contain html markup or yacs commands for display formatting. Here is a sample documentation block with a short and a long description:

/**
* return the date of Easter
*
* Using the formula from "Formulas that are way too complicated for anyone to
* ever understand except for me" by Irwin Nerdy, this function calculates the
* date of Easter given a date in the Ancient Mayan Calendar, if you can also
* guess the birthday of the author.
 */

Tags

Tags are single words prefixed by a "@" symbol. Tags provide additional information used to build the final documentation. All tags are optional, but if you use a tag, they do have specific requirements to parse properly.

The following snippet is a sample documentation block showing all possible tags. More tags may be added in the future, not all tags are implemented at this time in YACS, however they are all recognized as tags and will at least be displayed.

/**
* The short description
*
* As many lines of extendend description as you want.
* Below this goes the tags to further describe element you are documenting.
*
* @param  	type	description
* @return 	type	description
* @author 	author name url or email or text
* @tester 	tester name url or email or text
* @license	a url and an optional description
* @reference (if this tag is present, this script has to be copied to synchronizing servers)
* @see		link to the documentation page of another script
* @link 	http://www.example.com Example hyperlink inline link
* @todo		a verb and some words to describe a future action
*/

Examples

A sample documentation block placed at the beginning of a script:

/**
* parse PHP scripts to build the on-line documentation
*
* This class is derived from previous work originally coming from the Java world, by which
* developers have found a mean to auto-document their files.
...
*
* @todo add tags since and deprecated
* @see scripts/build.php
* @link http://phpdoc.org/ phpDoc web page
* @link http://sourceforge.net/projects/phpdocu project page
* @author Bernard Paques [email]bernard.paques@bigfoot.com[/email]
* @author Foo Bar [link]http://foo.bar.com/[/link]
* @tester Guillaume Perez [email]guillaume.perez@bigfoot.com[/email]
* @reference
* @license http://www.gnu.org/copyleft/lesser.txt GNU Lesser General Public License
*/

class PhpDoc {
  ...

A sample documentation block for a function:

/**
* return the day of the week
*
* @param string 3-letter Month abbreviation
* @param integer day of the month
* @param integer year
* @return integer 0 = Sunday, value returned is from 0 (Sunday) to 6 (Saturday)
*/
function day_week($month, $day, $year)
{
...
}

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

comment_block() - Process one comment block (internal use)

function comment_block($script, $signature, $comment)

$script - string the script file name
$signature - string the block signature
$comment - array the comment
returns the string to insert into the resulting page

generate() - Create the set of documentation pages

function generate()

get() - Get one comment

function &get($name)

$name - string the name of the comment to fetch
returns the resulting $row array, with at least keys: 'name', 'anchor' and 'content'

parse() - Parse one script to build the php documentation

function parse($script, $path='scripts/reference/')

$script - string one script
$path='scripts/reference/' - the path to access the script
returns either NULL or an error message

purge() - Delete all documentation pages

function purge()

setup() - Create a table for the php documentation

function setup()