PHP: Difference between revisions

From Elvanör's Technical Wiki
Jump to navigation Jump to search
Line 14: Line 14:


* Usage:
* Usage:
**Just document your source code using the standard PhpDocumentor tags (which are very similar to the Javadoc ones).
** Just document your source code using the standard PhpDocumentor tags (which are very similar to the Javadoc ones).
** You can also use *some*  HTML tags in your PhpDocumentor docblocks. A list is [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/DescHTML/_phpDocumentor---DescHTML.inc.html available here.]


* Compiling the source to an output format:
* Compiling the source to an output format:

Revision as of 16:07, 30 March 2007

This page will be a collection of resources on PHP programming.

Libraries

Documenting a PHP Project: PhpDocumentor

PhpDocumentor is the equivalent of Javadoc for the PHP language.

  • Installation under Gentoo:
    • You can use the ebuild in Portage. However the /usr/bin/pear script is broken and must be fixed else you won't be able to emerge PhpDocumentor. In this script the PHP interpreter is called with a memory_limit argument. Thus it won't use the default memory_limit set in the /etc/php/cli-php5/php.ini file. The memory_limit argument provided in /usr/bin/pear is too low (16M), thus you have to remove it. I consider this a Gentoo/PEAR bug.
    • Be sure to emerge at least PhpDocumentor 1.3.0 (currently in testing as of March 2007), as the RC versions are not stable enough.
  • Usage:
    • Just document your source code using the standard PhpDocumentor tags (which are very similar to the Javadoc ones).
    • You can also use *some* HTML tags in your PhpDocumentor docblocks. A list is available here.
  • Compiling the source to an output format:
    • Several outputs (HTML, HTML with frames, PDF...) are available. And for each of these outputs, several templates (controlling the style - CSS - and the display of the generated documentation) are available. Some are much better than other. I recommend using the HTML:Smarty:HandS one, which can result in the following shell command:
      phpdoc -d source_dir -t output_dir -o HTML:Smarty:HandS --title "This is the general title."
    • Other good templates include HTML:Smarty:PHP, HTML:frames:phpdoc.de or HTML:frames:l0l33t. Note that you can also generate the documentation from a PHP script running on the web server, but I think it is more convenient to use the command line tool.
  • Problems or things I'd like to change:
    • Currently I don't know how to remove line numbers from the generated documentation, although I would prefer not to include them.
    • I don't know how to tell PhpDocumentor that it is supposed to generate UTF-8 pages.