Automated API documentation for new releases
| From: | Martin Jansen | Date: | Wed, 14 Apr 2004 21:13:03 +0000 |
| Subject: | Automated API documentation for new releases | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-3464@lists.php.net to get a copy of this message | ||
Partially based on the ongoing discussion about adding the output of
phpDocumentor to the manual, I have revitalized an idea from a few
months ago:
Adding API documentation (*) to the manual is neither technically nor
conceptually a good idea. I'll not go into detail about this yet, but
if people are interested, I can explain the rationale in another mail.
(Most of the reasons can also be extracted from the list archives.)
So instead I suggest to publish API documentation for each release of a
package outside of the manual. Concretely this means that the API
documentation for DB 1.6.2 will be available at
http://pear.php.net/docs/DB/1.6.2/, while the
documentation for release
2.0.1 will be available at /docs/DB/2.0.1/ etc.
No work on the side of the maintainer is required, because everything is
done remotely on the webserver.
This solution is certainly not perfect, but it at least solves one of
the most pressing documentation problems in a relatively easy way. I
have already implemented about 90% of the required changes for
pear.php.net.
(*) The term "API documentation" refers to the HTML-based documentation
produced by phpDocumentor.
--
- Martin Martin Jansen
http://martinjansen.com/