Re: Requirements for Documentation System
| From: | Stefan Neufeind | Date: | Tue, 13 Apr 2004 12:28:56 +0000 |
| Subject: | Re: Requirements for Documentation System | ||
| References: | 1 | Groups: | php.pear.doc |
| Request: | Send a blank email to pear-doc+get-3312@lists.php.net to get a copy of this message | ||
On 12 Apr 2004 at 20:22, Paul M Jones wrote:
> > As for the requirements, if you're really serious about reconsidering
> > the whole PEAR-DOC architecture (which I think is useless except for
> > integrating Livedocs), you should add that the docs can be generated
> > from source code, as with PHPDocumentor.
>
> I don't know if we're reconsidering the whole architecture, we just
> want to see what the requirements for the architecture are. If we're
> on-track, then great! If not, though, we need to see where we want to
> go before we can try to get there.
>
> The "pull from phpDocumentor" is a fantastic idea. I don't know if we
> want to generate the whole of the documentation from source code only,
> as that might present problems with integrating other sources of
> editing, but certainly the general idea is sound.
>
> Add new requirement: a way to integrate inline phpDocumentor tags from
> source code (method and purposes to be determined).
And maybe in that connection: Allow for completely auto-generated API
doc from source (like the one generated by phpDoc currently) and
optionally add additional pages. I'm thinking about a first step to
introduce appropriate phpdoc-comments in those places where they are
still missing - at least parameter-listing and a short "what does
this function do" description.
Since I expect when we do this there will be a lot of API docs that
are auto-generated maybe we need some way to clearly hightlight
"handwritten" introductions, examples etc. that are not integrated
from source using phpdoc.
However, I'd like to see that everybody works on phpdoc-comments
first (!) since they are directly bundled and shipped with the
package. Separate docs, like they exist for some classes currently,
should imho be an additional piece of work. So maybe even some
currently present docs could be refactored in phpdoc, and only some
parts which don't fit into phpdoc nicely or which are too extensive
to be part of the source, should imho be added to the doc directly.
Stefan