[wp-hackers] Inline documentation
dmhouse at gmail.com
Fri Feb 17 16:18:51 GMT 2006
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()
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
More information about the wp-hackers