Re: peardoc2

From: Date: Thu, 16 Jan 2003 20:58:49 +0000
Subject: Re: peardoc2
References: 1  Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-284@lists.php.net to get a copy of this message
Alexander Merz wrote:
As you see on the CVS commits, i worked on peardoc2 last week heavily. DB_DataOjects will be finished today. So peardoc2 will be ready for public release! Please take a look on peardoc2, if no one say -1, we can release it this week. (I will publish a HTML-version for reading at the end of the day) Hello Alexander,
even I'm new to peardoc, +1 for publishing it. I had a short glance to the peardoc2-rep., and some small questions and suggestions came into mind: - all subchapters of 'PECL Packages' have roman numbers while all others have normal numbers - is this intended, or a bug in the styles? - I've already requested karma for pear and peardoc, so I don't mention the typos and small bugs here, but will commit them later. But: There is a planned system mentioned, which should create the docbook-code automatically out of the php-files (as far as I've understood ;) -> is there somewhere more info about it (Does/will it apply only for selected or all package-files, etc.)? - Just some suggestions, since pear and the doc will grow: - I'd use also .cvsignore for the result-files (e.g. configure as a
    result of configure.in), so that "global" committers don't commit
    accidentially these files and produce so much unnecessary
    cvs-traffic.
- I'd also integrate the 'make-pearweb.sh' in the makefile.in - You've mentioned in the docs the "phpdoc-tools"-dir for win-users like in the phpdoc-group, but configure.in doesn't check for the php.bat there. So I'suggest to eighter document that the arg --with-php... has to be provided, or implement this check like in the phpdoc-group (works fine there), and document the needed bat-file. More general things: - Who is the target audience for the package-descriptions? Why I ask: e.g. parse() from HMTL_Template_IT has documented the following syntax (btw, "__global" should be "__global__", and "IntegratedTemplate" should be "HTML_Template_IT"): void IntegratedTemplate::parse ([string $block = "__global" [, boolean $flag_recursion = false]]) If the aimed audience is the user who cares just for the interface, but not for the class-source: shouldn't this internal default VALUE be omitted, and the default BEHAVIOR described in the text? (e.g. "__global__" is only internally used, and nowhere else documented here). Hmm... On the other hand, if the source-comments get autogenerated to the manual, this question might be bogus. - Translations: My experience from phpdoc shows, that we invest MUCH more time for the maintenance of the translated files than for the transl. itself. So the question is if there would be a tool similar to phpdoc's 'revcheck' useful. So I think these are enough thoughts for the moment ;) Cu, Thomas

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