[wp-hackers] Inline documentation

[Arne Brachhold]

Hi,

>> /**
>>   * @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?

that's the phpDoc syntax. A list of valid tags is available at
http://www.phpdoc.de/kongress/tags.html (Sorry, in German only).

The advantage of this system is that there are a lot of PHP
IDEs which parse these tags and show the parameters if you
start typing the function name (autocomplete).

The phpDoc syntax is widely used and easy to read and learn.
Of course, it has a little more overhead compared to your
solution, but I would prefer to chose a sytax which is already
used and has software support like tools for building 
documentation pages.

A full phpDoc comment for a method or function can look like
this:

/**
* First Line: Short text about the function.
* 
* More detailed comment about the function
* Overview first, then detailed comment and tags.
* 
* @param  string   $param1 Description of parameter 1
*                  Can have multiple lines two.
* @param  string   $param2 Another param
* @return boolean  False on a problem, true on success
* @see    otherfunction(), $othervar, myClass::myMethod()
* @deprecated 2.1 - 2000/12/06
* @link http://codex.wordpress.org/Removed_functions Add. info why deprecated
*/
function render($param1 , $param2) { 
   if(problem()) return false;
   else return true;
}


Arne