[wp-hackers] Inline documentation

[David House]

On 17/02/06, Owen Winkler <ringmaster at midnightcircus.com> wrote:
> 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
>   */

As Matt has expressed his distaste for comments before really short
functions, here's a more complicated example for list_cats()
(attached).

Issues raised by writing this:

* I found four completely pointless parameters. Four! (the three
listed as 'Doesn't seem to do anything', then $hierarchical as well)
Here shows the benefits of documenting.
* I hope the format is to taste, I didn't bother with anything other
than @param and @return.
* What to do about functions that don't return anything? @return
nothing, @return null or just no @return at all?
* Hopefully my explanations of the parameters were clear enough.
No-one ever has to go through that function again, they just check the
reference at the top.

--
-David House, dmhouse at gmail.com, http://xmouse.ithium.net
-------------- next part --------------
/**
* Output a list of categories
* 
* @param $optionall				Doesn't seem to do anything
* @param $all					Doesn't seem to do anything
* @param $sort_column			string; Which column in the categories table to order the results by. Default 'ID'
* @param $sort_order			'asc' | 'desc'; Whether to order ascending or descending. Deafult 'asc'
* @param $file					Doesn't seem to do anything
* @param $list					bool; If true, output as a <ul>, otherwise just seperate categories with a <br/>. Default true
* @param $optiondates			bool; Whether to output dates of when the last post was published to each category. Default false
* @param $optioncount			bool; Whether to output a count of the number of posts in each category. Default false
* @param $hide_empty			bool; Whether to hide categories with no posts in them. Default true
* @param $use_desc_for_title	bool; Whether to use the category's description for the title attribute of the link.  Default true
* @param $children				bool; Whether do display category children for each category. See also $hierarchical. Default false
* @param $child_of				int; The ID of the category you want to display. Default 0 = all categories
* @param $categories			array or 0; The array of categories to iterate over. Default 0 = get all categories from DB
* @param $recurse				bool; Don't set, is used as a state parameter when internally recursing. Default 0
* @param $feed					string; Set to the name of a feed if you want to output links to the feed for each category. Default ''
* @param $feed_image			string; Set to an image URL if you want to output an image and a link as above. Default ''
* @param $exclude				string; A comma seperated list of category IDs of categories to exclude. Default ''
* @param $hierarchical			bool; exactly the same as $children: you must set both for them to take affect. Default false
*/