Better comments phpdoc on functions

[eluser]Lechuss[/eluser]
Hi,

Would you - Developers - write a better comments on functions? Something like that:

GOOD:

Code:

/*
* Generates a SELECT MAX(field) portion of a query
  *
  * @param string the field
  * @param string an alias
  * @return object
  */
public function select_max($select = '', $alias = '')

BAD (missing description of pamateres):

Code:

/**
* Sets the OR HAVING value
*
* Separates multiple calls with OR
*
* @param string
* @param string
* @return object
*/
public function or_having($key, $value = '', $escape = TRUE)

It helps to work with autocomplete in Netbeans.

[eluser]Aken[/eluser]
You're welcomed to help contribute on Github.

[eluser]Lechuss[/eluser]
Another one questions about comments:

Use Having for example:

Code:

/**
* Sets the HAVING value
*
* Separates multiple calls with AND
*
* @param string
* @param string
* @return object
*/
public function having($key, $value = '', $escape = TRUE)
{
return $this->_having($key, $value, 'AND ', $escape);
}

Shouldnt it be?:

Code:

/**
* Sets the HAVING value
*
* Separates multiple calls with AND
*
* @param string key
* @param string value
* @param string escape=TRUE  <---- third parameter?
* @return object
*/
public function having($key, $value = '', $escape = TRUE)
{
return $this->_having($key, $value, 'AND ', $escape);
}

[eluser]Aken[/eluser]
Yes, all parameters should be documented.