Re: Requirements for Documentation System

From: 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

« previous php.pear.doc (#3312) next »