+- CodeIgniter Forums (https://forum.codeigniter.com)
+-- Forum: Archived Discussions (https://forum.codeigniter.com/forumdisplay.php?fid=20)
+--- Forum: Archived General Discussion (https://forum.codeigniter.com/forumdisplay.php?fid=21)
+--- Thread: Better comments phpdoc on functions (/showthread.php?tid=52048)
Better comments phpdoc on functions - El Forum - 05-28-2012
[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.
Better comments phpdoc on functions - El Forum - 05-28-2012
[eluser]Aken[/eluser]
You're welcomed to help contribute on Github.
Better comments phpdoc on functions - El Forum - 05-29-2012
[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);
}Better comments phpdoc on functions - El Forum - 05-29-2012
[eluser]Aken[/eluser]
Yes, all parameters should be documented.