PHPBuilder - How To Document Your PHP Classes Page 5



RSS Twitter
Articles Code Documentation

How To Document Your PHP Classes - Page 5

by: Stefano Locati
|
August 25, 2000

How To Modify The Script For PHP

The original HeaderDoc script from Apple is meant for C or C++ headers, so it has to be slightly modified to use it with PHP. If you're not interested about details you can just download it and skip to the next section.
The only thing to modify in the sources is in the main perl file and it's made to make the script accept .php and .php3 extensions.
$ diff headerDoc2HTML.pl /usr/local/bin/headerdoc2html
195c195
<     ($rootFileName = $filename) =~ s/\.(h|i)$//;
---
>     ($rootFileName = $filename) =~ s/\.(h|i|php|php3)$//;

Running The Script

After having installed the script, supposing that your classes are in the classes subdirectory and that you want to put the generated documentation in the docs directory, you should issue this command:
headerdoc2html -o docs classes/*.php
Unfortunately if there are multiple PHP files, this script has the bad habit to split those files in different directories, making navigation among classes' documentation more difficoult. Moreover since the original script was written for C/C++ header files that are just declarations of classes and functions and have no definitions for them, it outputs all the code following the function name until a ; is found, so tipically the first line of code.
But before you get desperate after all the effort reading till now, relax because I wrote a simple script to solve both these problems.
cat classes/*.php | sed 's/ *{/;#{/g' | tr "#" "\n" > docs/all.php
headerdoc2html -o docs docs/all.php
rm docs/all.php
If you're wondering why I use the tr utility here instead of doing all the job with sed, the reason is that sed 3.02 that is still used on RedHat 6.2 doesn't handle newlines. The new version sed 3.02a would be needed instead. If you're curious see the SED FAQ.
Good luck with your documentation effort!
--Stefano

« Previous Page
1
|
2
|
3
|
4
|
5

Comment and Contribute

Your comment has been submitted and is pending approval.

Author:
Stefano Locati

Comment:



Comment:

(Maximum characters: 1200). You have characters left.