How To Document Your PHP Classes Page 5

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 Locati

–Stefano