Re: PEAR Guide/Docs

Bertrand Mansion wrote:

What's the difference between peardoc and peardoc 2 ? Why was it decided to change versions ? Is documentation in peardoc 2 really peardoc 2 formatted ? peardoc2 is more scalable, peardoc followed the php manual structure which doesn't fits

I did look at XML_Tree in peardoc 2 and I didn't get this feeling. Almost every packages are documented in different ways, some have tutorials, others have only method description, is this normal ? Yes, i can write the methods desc based on the phpdoc comments, but not an introduction without any starting point.

I would like to make doc for the new Config package but it is actually composed of 2 main classes Config and Config_Container. I thought that if I look at the way XML_Tree is documented, I could find a template for documenting Config because there is XML_Tree and XML_Tree_Node. But XML_Tree_Node is not documented and I couldn't figure out how to insert Config_Container in peardoc structure. Hm, why don't you take a look into the authoring section?!

package/ config.xml config/ intro.xml config.xml config-container.xml config/ parseconfig.xml ... config-container/ additem.xml ... The doc for config-container (and xml_tree_node) is optional, if they are private classes.

I was not talking about docbook by itself but the way it is used in conjunction with peardoc. Writing documentation should be made easy and that's not currently the case, look at the number of packages without proper documentation. If have no problem to write docs, if:

1. correct doc commands are used http://www.pearfr.org/~amerz/pear/peardoc2/package.php.html#package.php.phpdoc and not nonsense like (one of the harmless):

    /**
     * Extension dependencies check method
     *
     * @param string $name        Name of the extension to test
     * @param string $req_ext_ver Required extension version to compare with
     * @param string $relation    How to compare versions with eachother
     *
     * @return mixed bool false if no error or the error string
     */

function checkExtension(&$errmsg, $name, $req = null, $relation = 'has') (missing access tag, $req_ext_var instead of $req, missing @param $errmsg) 2. there are an intro and optional examples in the package

I already wrote a tutorial for HTML_Table a long time ago. I started one about HTML_QuickForm a few month ago, sent the beginning to Alexander Merz and never had any feedback. It was actually written directly in docbook. I can remember that i reviewed it - and that there were no big mistakes. If i forget to send you a note, i would like to apologize!