SourceForge.net LogoMdoc technical reference

This page provides author notes used to design the Mdoc class processings.

Basics

Variables in PHP are represented by a dollar sign followed by the name of the variable. The variable name is case-sensitive.

Variable names follow the same rules as other labels in PHP. A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'

For our purposes here, a letter is a-z, A-Z, and the ASCII characters from 127 through 255 (0x7f-0xff).

A documenting comment starts with /** followed by a blank character (the Perl \s char, usualy space or new line).

The documention parsing starts as of the first documenting comment, except for the CVS keyword parsing, thus some undocumented code can preceeds the constant, library or class declaration .

Example:

<?php
/**
* A method for auto-documentation commenting.
*
* Every code documenting block, like this one, has the same format;
* the very first line is the "short description", following lines up
* to first @info is the "long description". Every @info comment starts
* a line with @ (more precisely \n * @ sequence); they are also called
* active comments (sometimes written @ctive comments).
*
* The long description is optional.
*
* For PHP interpreter, the default scope is "public" (so @private
* and @protected should not be forgotten in PHP4 classes).
*
* @warning  This method is a good commenting example.
* @experimental
* @private
* @param (mixed) $p1 a text (string) as regular entry
*                    or false (bool) to get a particular behavior
* @param (array) $p2 a structured list:
*                    'name' => the user name
*                    'address' => the user address
*                    'city' => the city name
* @return (void) if echo flag $p1 is true,
*                the comment continue on a three
*                lines to test return values parsing
*         (string) the printable result if echo flag is false
*/
function example($p1, $p2) {

  if (
$p1) {
    return;
  } else {
    return
"whatever";
  }
}
?>

Constraints and recommendations

While PHP allows a lot of various comment styles, the Mdoc parser doesn't support too weird and ugly comment styles. This limitation provides constraints which help in commenting code nicely.

Characters /** in comments

The sequence /** must be quoted in code comments to avoid the parser to split the code fragment within a comment.

<?

// Don't do this:

// Starting "/**" is NOT part of fragments at this stage, so remove "/* ... */"
$source_frags[$index] = preg_replace('!/\*.*\*/!s', "", $fragment);

// but do this

Starting "/**" is NOT part of fragments at this stage, so remove "/* ... */"
$source_frags[$index] = preg_replace('!/\*.*\*/!s', "", $fragment);
?>

Usage of @ char in descriptions

If you start a line with @ in the long description, the parser will consider it as the fist @info keyword, which isn't wht you expect.

<?

// Don't do this:

/**
 * Syntactically correct PHP5 class example.

 *
 * For PHP interpreter, the default scope is "public" (so @private and 
 * @protected should not be forgotten).
 */

// but do this

/**
 * Syntactically correct PHP5 class example.

 *
 * For PHP interpreter, the default scope is "public" (so @private  
 * and @protected should not be forgotten).
 */
?>

Commenting in constant declarations

Commenting in between the const keyword and the constant identifier is not allowed, as well as var keyword and property identifier (PHP4) :

<?php
 
/* These styles are not allowed (and somehow ugly) */ 

const  // An in-class constant definition comment
  START = 0;  
  
const 
  // An in-class constant definition comment
  START = 0;
  
/* Recommendation (the 1st is prefered)*/  

const START = 0;  // An in-class constant definition comment

/* Same scheme for PHP4 properties */

var  // A property definition comment
  $myprop = 0;  

/* Recommendation */  

var $myprop = 0;  // A property definition comment

?>

Commenting in between the define keyword and the constant identifier is not allowed:

<?php 

/* This style is not allowed (while is weird but is correct PHP syntax) */ 

define(  
         // Real code comment to ignore
         "CLAS_INTERNAL_FOUR", 
         4);

/* Recommendation, the 2nd might be prefered */

         // Real code comment to ignore  
define(  "CLAS_INTERNAL_FOUR", 
         4);

// Real code comment to ignore  
define("CLAS_INTERNAL_FOUR", 
       4);

?>

For constant declaration in group, the subcomment must be one line and you'd keep the block somehow simple to ensure a correct parsing by Mdoc parser. If the block is too complex, with many subcomments, it's recommended to declare the constant individually. Here is a good example of constant block declaration:

<?php 

/**
 * New line chars.
 *
 * This is the long description for the whole block, so it applies
 * to every constant.
 */
const NL_DOS = "\r\n";  // for Windows environment
const NL_MAC = "\r";    // for Mac environment
const NL_NIX = "\n";    // for Unix/Linux environment

/**
 * New line chars.
 *
 * Use # inline comment to exclude these sbucomment from the source
 * code documentation.
 */
const NL_DOS = "\r\n";  # inline comment ignored for documenting
const NL_MAC = "\r";
const NL_NIX = "\n";

?>

Comment elements not allowed

For obvious consistency reasons (and internal represention choices), some comment info keys aren't allowed,

not allowed in any comment:

@short_description
@long_description
@cvs

not allowed in library comment:

@name
@comment

not allowed in class comment:

@name
@declaration
@comment
@line
@extends (PHP5)
@implements (PHP5)
@final (PHP5)
@abstract (PHP5)
@interface (PHP5)

not allowed in method and function comment:

@code
@comment
@line
@final (PHP5)
@public (PHP5)
@private (PHP5)
@protected (PHP5)

not allowed in property comment:

@code
@comment
@line
@initial
@static (PHP5)
@public (PHP5)
@private (PHP5)
@protected (PHP5)

In constant and constant group comment, the only comment info keys allowed are:

@experimental
@type
@warning

When the Mdoc parser encounters such a comment element, a parsing error is issued at warning level.

Support of CVS keywords comments

Mdoc class supports the CVS keywords declared is anu block or full-line comments:

$Author: ...$
$CVSHeader: ...$
$Date: ...$
$Header: ...$
$Id: ...$
$Name: ...$
$Locker: ...$
$Log: ...$
Revision 1.5 2005/10/07 13:44:48 joe
CVS commit message entered by Joe to describe this revision

Revision 1.4 2005/10/07 13:43:27 fred
CVS commit message entered by Fred to describe this revision

$RCSfile: ...$
$Revision: ...$
$Source: ...$
$State: ...$

If Mdoc finds other CVS keywords, they are ignored. If the same keyword is found several tmimes, only the first one is retainded, following ones are ignored, considering they are regular comments.

$Author$
The login name of the who checked in the revision.

$CVSHeader$
A standard header (similar to $Header$, but with the CVS root stripped off). It contains the relative pathname of the RCS file to the CVS root, the revision number, the date (UTC), the author, the state, and the locker (if locked). Files will normally never be locked when you use CVS.

Note that this keyword has only been recently introduced to CVS and may cause problems with existing installations if $CVSHeader$ is already in the files for a different purpose. This keyword may be excluded using the KeywordExpand=eCVSHeader in the `CVSROOT/config' file.

$Date$
The date and time (UTC) the revision was checked in.

$Header$
A standard header containing the full pathname of the RCS file,
the revision number, the date (UTC), the author, the state, and
the locker (if locked). Files will normally never be locked when
you use CVSNT.

$Id$
Same as $Header$, except that the RCS filename is without a path.

$Name$
Tag name used to check out this file. The keyword is expanded only
if one checks out with an explicit tag name. For example, when
running the command cvs co -r first, the keyword expands to Name:
first.

$Locker$
The login name of the who locked the revision (empty if not
locked, which is the normal case unless cvs admin -l is in use).

$Log$
The log message supplied during commit, preceded by a header
containing the RCS filename, the revision number, the author, and
the date (UTC). Existing log messages are not replaced. Instead,
the new log message is inserted after $Log:...$. Each new line is
prefixed with the same string which precedes the $Log keyword. For
example, if the file contains

    /* Here is what people have been up to:
    *
    * $Log: frob.c,v $
    * Revision 1.1 1997/01/03 14:23:51 joe
    * Add the superfrobnicate option
    *
    */
then additional lines which are added when expanding the $Log keyword
will be preceded by * . Unlike previous versions of CVSNT and RCS, the
comment leader from the RCS file is not used. The $Log keyword is useful
for accumulating a complete change log in a source file, but for several
reasons it can be problematic. See Log keyword.

$RCSfile$
The name of the RCS file without a path.

$Revision$
The revision number assigned to the revision.

$Source$
The full pathname of the RCS file.

$State$
The state assigned to the revision.

Bugs

If Mdoc class fails to document your code correctly, you may submit it by mail to jmfaure at users.sourceforge.net ; please ensure your code is parsed without error by PHP before sending it.