Hi folks
A possible new approach to generating automatic documentation from
source code - but it will require someone with good C++ skills to
evaluate it...
One of the weaknesses of PHP is that it lacks a built-in Javadoc style
system for generating automatic documentation in HTML and other
formats direct from the source code. On larger projects, this could
obviously save very substantial amounts of time.
There are a number of approaches to solving this for PHP - either
clones of Javadoc written in PHP, or an interface to Javadoc itself.
See the article and comments at:
http://www.phpbuilder.com/columns/stefano20000824.php3
The problem is, to my eye at least, that the Javadoc style of markup
is intrusive and reduces the readability of the code. And the php
imlementations are still incomplete with pretty basic feature sets.
A possible alternative: the programmers at CERN (the guys who invented
the WWW) have a free, high-end data processing framework called ROOT,
and this includes a documentatation generation component. You can find
it at:
http://root.cern.ch/root/
With the documentation specific stuff at:
http://root.cern.ch/root/Documentation.html
There are binaries for most platforms, and the source code is there
too.
This is seriously cool software, but the interface is in C++. I
suspect that using this tool anyone with C++ skills could quickly
develop a leading edge documentation engine for PHP that would more
than match the alternatives in PERL and Java (it generates very
impressive diagrams of class trees, for a start).
A full featured, native documentation engine would surely help to
establish PHP as a serious corporate tool (anyone at Zend
interested??) and would be a great utility for any larger project.
Unfortunately, I am merely a PHP hacker with no background in C. If
anyone with C++ skills is interested, it would be great if they could
check out the potential of ROOT at Cern, and report back to the list.
If it looks promising, and someone was prepared to take it on, perhaps
we could have a discussion about the markup format that should be
employed. Ideally, the interface would allow the user to select from a
range of markup styles, rather than impose a style on all users...
Any takers?
Geoff Caplan
Caplan Associates
33 Pytchley House
Brown's Green
Birmingham B20 1DN United Kingdom
Voice: (+44) 0121-515 1154
mailto:[EMAIL PROTECTED]
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
To contact the list administrators, e-mail: [EMAIL PROTECTED]
