[wp-hackers] Inline documentation

[Owen Winkler]

Rich Bowen wrote:
> Abhay Kumar wrote:
>> /**
>>   * @param type string 'mysql' | 'timestamp'
>>   * @param gmt boolean
>>   * @return whatever
>>   */
>> function current_time($type, $gmt = 0) {
> 
> The syntax "@param" doesn't mean anything to me. Why "@" on that? Is
> that supposed to signify something that I'm missing?
> 

Using "@param" allows existing documentation parsers to extract the 
documentation you've provided.

Using the short format you suggested, you would need to write a whole 
new parser to extract the parameters.  If you use the @param PHPDoc 
format, then PHPDocumentor can produce searchable HTML documentation, 
and editors like Zend's Dev Studio can provide live parameter insight. 
This documentation style is pretty standard in PHP projects, and is used 
it a lot of PEAR code that I've seen.

If you use the style you suggested, it will be difficult to build a 
parser to output non-source code developer documentation, because there 
is no token to indicate that your comment is anything special.

To nitpick a little:
* There isn't really a need to include the function name since it's 
right there under the comment
* The comment doesn't say what the function does/what thing the function 
returns

Using this particular function as an example, I don't know if I'm going 
to get a unix timestamp integer or a string-format in response.  I also 
don't know if it is going to return system time or MySQL time.

Here's (IMO) a reasonable PHPDoc comment:

/**
  * returns the system time in the format specified by $type
  * @param type string 'mysql' | 'timestamp'
  * @param gmt boolean
  * @return mixed
  */

Owen