Re: PHPDoc comments suggestions

Greg Beaver wrote:

Thanks for your feedback on the peardoc2 converter, I've done a bit more work on it based on the results of testing, and are ready for the next round of testing from you users, to make sure output is acceptable.

Some notes: - all underscores in tag id's and filenames must convert to "-" - drop the summary file, it is unnecessary, providing a summary in a meta language like docbook makes no sense. The note about inheritance should be add to {package-name}.xml, ie: --- <sect1 id="package.category.package"> <title>package</title> &package.category.package.intro; ... &package.category.package.class.function; <para>inherited from <link...></para> &package.category.other-package.other-class.function; --- - use <variablelist> instead of <itemizedlist> for parameter description <variablelist>

      <varlistentry>
       <term>
        &type.string;
        <parameter>$storageDriver</parameter>
       </term>
       <listitem>
        <para>
         name of the storage driver that should be used
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        &type.string;
        <parameter>$loginFunction</parameter>
       </term>
- the access section is nonsense, the pear manual covers public functions only
- the notes section is missing - it should contain at least a note about static/ not static

- add the throw section also if @throw not given - there is a big bug in the file logic - the category file contains the entries for the classes of the packages - and uses the wrong tag and id: ---- <sect1 id="package.category.package"> <title>package</title> &package.category.package.class; --- must be: --- <chapter id="package.category"> <title>category</title> &package.category.package; --- - the {package-name}.xml is completly missing But in general: really good work, go ahead! :-)