Proposal for "PHP_GenDocBlock"

» Metadata » Status
» Description
Creation of Documentation blocks or DocBlocks in a PHP file.

Creates the file Page block and the DocBlocks for includes, global variables,
functions, parameters, classes, constants, properties and methods.
Accepts parameters to set the category name, the package name, the author's
name and email, the license, the package link, etc...
Attempts to guess variable and parameters types.
Aligns the DocBlock tags.
Tags are not updated or added to existing DocBlocks but only realigned.
Includes regression tests.

The package can be run by: calling the "PHP_GenDocBlock" class, or
by running the "gendocblock" DOS/Unix command.

<pre>
Example 1: Creates DocBlocks in foo.php with default license, package name, etc...
$gendocBlock = new PHP_GenDocBlock();
$gendocBlock->run('foo.php');

Example 2: Creates Docblocks for foo.php in docfoo.php with some specific Page tags
$param = array('license' => 'apache20', 'category' => 'PHP',
'author' => 'John Foo', 'email' => 'jfoo@mail.com', 'year' => '1999-2007');
$gendocBlock = new PHP_GenDocBlock();
$gendocBlock->run('foo.php', $param, 'docfoo.php');

Example 3: Realigns DocBlock tags
#gendocblock -A foo.php

Example 4: Creates Docblocks for foo.php in docfoo.php with some specific Page tags
#gendocblock -la -c PHP -a "John Foo" -e 'jfoo@mail.com' -y 1999-2007 foo.php docfoo.php
» Dependencies » Links
  • NA
» Timeline » Changelog
  • First Draft: 2007-04-28
  • Proposal: 2007-04-28
  • Call for Votes: 2007-05-20
  • Michel Corne
    [2007-05-07 16:42 UTC]

    Some minor bug fixes and enhancements, see details in CVS log.
    Links in the Proposal main page updated to reflect those changes.
    As per some folks' requests the package can be downloaded or the code can be browsed from sourceforge.
    Looking forward to your feedback. Thanks,
    MC
  • Michel Corne
    [2007-05-11 19:42 UTC]

    Changed the package/main class name to GenDocBlock
    Split the main class into several smaller manageable classes.
    Changed the license to BSD.
    Generates Page-level DocBlock with a BSD license as default.
    Fixed the missing static tag of some static functions.
    Suppressed the generation of DocBlocks for static variables within functions.
    Suppressed the generation of DocBlocks for includes within functions.
    Displays the right (incremented) error line number for tests.
    Displays "unknow" instead of "mixed" for undetermined variable types.
    Fixed the capture of function/method names when they return by reference.
    Enhanced the types caching.