Php Documentation generator
Purpose
As of June 2000, no documentation generator for php source files was
available. So I need to write one myself, since I had just finished
my first php project and needed a tool to generate some documentation
out of the source code, which where about 30 files at that time.
First, I tried it with php, but soon the deficiencies of php (and of
most other interpreted languages), mainly speed issues in the field of
tree walking, forced me to use a compiled language. I decided on using
pascal, since I was involved with a large delphi project. There is
a excellent free pascal compiler for Linux
and other OSs available.
Screenshots
For the curious, I made some screenshots.
How it works
phpDoc needs some input files on the command line. It then opens
each given file, builds a list of tokens (smallest unit of chars which
make sense) and then tries to read the programs structure from that token
stream. It fills some arrays with variables and classes and functions and
whatever it comes across.
Having done that for every file, it generates output. Currently, phpDoc
can write text files (who had guessed that ?), latex and html.
All desciptive strings are stored in a configuration file. The
filename is "phpdoc.conf" but may be changed by a command line option.
phpDoc even tries to guess your language. Currently, english and
german are supported.
What you need to do to create shiny documentation
Get the source code
Real men[tm] compile themselves. They just download the
source. People who use to park their cars in
shadowy places (aka Schattenparker) may also
Get the binaries
If your operation system crashes on you on a regular base, you may
want the windows exe. Linux people
without the free pascal compiler can get a
Linux binary as well.
Unpack the download
You should be able to do that yourself. Zip-files are unpacked with
gzip, tgz-files are unpacked with "tar xfzv <somefile>".
Start phpDoc
Now make some backups of your php project. Then try to run phpDoc
against your source by typing in "phpdoc -latex -html <someOfYourFile>". phpDoc
understands multiple files, as well as wildcards.
Enjoy the output
The generated files will be phpDocuout.latex, <someOfYourFile>.out.html and
indexout.html.
Now run latex against the latex file "latex phpDocuout.latex" and do with
the dvi whatever you want. I like to impress my customers with
pdfs, so I run "pdflatex phpDocuout.latex". Please do the latex run twice,
so latex can build the table of contents in the first run.
Command line options
Always ask phpDoc for itīs options by just calling it without
parameters.
Parameters are
- v - be verbose
- html - generate html output
- latex - generate latex output
- text - generate text output
- f<file> - use different config file
- createenglish - create english config file
- creategerman - create german config file
Know bugs
Works only with php-files. They probably must start with
<?php. I never tested with HTML/PHP3 -
mixed files, since I donīt use them.
To do
- Cross reference table. Real soon.
- Better source documentation. Maybe.
- Other languages (e.g. Pascal). Weīll see.
- Maybe use lex as scanner. But itīs really fast now...
Compiling
Free pascal
Just type "ppc386 -Sd phpdoc.dpr". The option "Sd" turns
basic delphi support on, which is badly needed.
Delphi
Delphi is a Windows pascal compiler from Borland/Inprise/
Borland/Corel or what the name this week is. Fire delphi
up and load "phpdoc.dpr". Click the "Run"-Button. Ready.
Legal stuff
phpDoc comes without any warranty. Use at own risk.
Copying
phpDoc is open source. It is gplīed. Do with it
whatever you wish to do. If you enhance the source,
please email me,
so I can keep this site updated.
Return to homepage
enail
Last modified: Fri Jun 9 12:55:40 CEST 2000