Re: Automated API documentation for new releases
| From: | Stefan Neufeind | Date: | Fri, 16 Apr 2004 11:46:22 +0000 |
| Subject: | Re: Automated API documentation for new releases | ||
| References: | 1 | Groups: | php.pear.doc |
| Request: | Send a blank email to pear-doc+get-3533@lists.php.net to get a copy of this message | ||
On 14 Apr 2004 at 23:13, Martin Jansen wrote:
> 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.
You are refering to the HTML-based documentation? Hmm, and how about
the peardoc2-based API-documentation generated by phpDocumentor? I'm
asking because it might mean that packages which do their best to
have good and maybe at some point "complete" API-docs in phpdoc-
format (which is a good thing imho) might be counted as "package
without doc"?
Stefan