Some Chem classes for PEAR and problem in PHPDoc

Been PEAR-ifying some of the classes I've made, and so
far I have a set of basic Chemistry related classes
that I would like to contribute to the PEAR CVS rep,
but I do not have enough Karma to do that. 

Also working on modifying my (still under development)
numPHP package (to manipulate matrices, vectors,
complex numbers, etc) to comply w/ the PEAR specs.

The problem in PHPDoc I observed is that the following
piece of code:

    /**
     * Constructor for the class, requires the element
symbol
     * and an optional array of coordinates
     *
     * @param   string  $element    chemical symbol
     * @param   optional array   $coords     array of
coordinates (x, y, z)
     * @access  public
     * @return  object  Chem_Atom
     *
     * @see     setCoordinates()
     */
    function Chem_Atom($element, $coords="") 

does not generate the expected prototype:


   object Chem_Atom  Chem_Atom(string $element, [
array $coords ])


but a wrong prototype:


   object Chem_Atom  Chem_Atom(string $element, [
string $coords ])


And the report generated by PHPDoc says:

[function] chem_atom                       mismatch  
2nd parameter type '$coords' does match the the
documented type 'array', possible
error consider an update to '@param string $coords
array of coordinates (x, y, z)' or
'@param string array of coordinates (x, y, z)', the
variable name is optional.

I think that the code is trying to be a little too
smart, because if I change my function definition to:

     function Chem_Atom($element, $coords=array())

it generates the correct prototype. But, that is
incorrect for PHP (using 4.0.4pl1), you cannot assign
an array as a default value for an optional parameter,
this is known, and gives a parsing error if you try to
run code that has that. 

IMHO, until PHP supports such as construct, the PHPDoc
code should honor the tag spec and not try to second
guess the programmer, emitting a warning is OK,
writing the wrong is not.

BTW, I am using the latest PHPDoc form the PEAR CVS.



=====
--- Jesus M. Castagnetto ([email protected])

__________________________________________________
Do You Yahoo!?
Get personalized email addresses from Yahoo! Mail - only $35 
a year!  http://personal.mail.yahoo.com/