[wp-trac] Re: [WordPress Trac] #3982: post.php inline documentation

[WordPress Trac]

#3982: post.php inline documentation
--------------------------------------------------------------------+-------
 Reporter:  m0n5t3r                                                 |        Owner:  anonymous
     Type:  enhancement                                             |       Status:  new      
 Priority:  normal                                                  |    Milestone:  2.3      
Component:  Administration                                          |      Version:           
 Severity:  normal                                                  |   Resolution:           
 Keywords:  has-patch needs-testing 2nd-opinion developer-feedback  |  
--------------------------------------------------------------------+-------
Changes (by jhodgdon):

  * keywords:  has-patch needs-testing 2nd-opinion => has-patch needs-
               testing 2nd-opinion developer-feedback

Comment:

 I think it is a great idea to add documentation to the PHP functions of
 WordPress, if it is correct and descriptive.

 However, there are two proplems with the proposed patch, in my opinion:

 1) Not all the doc is correct (I think). For instance, the first function
 I believe returns the attachment's file name, but the doc says "returns
 meta data", which is sort of true but not very specific. The second
 function doc is similarly misleading.I sort of stopped reading at this
 point, so I'm not sure how many other functions are not correctly
 documented.

 2) Style: the descriptions are too short, and the "return" sections give
 the data type but not a description of what the value is. The style is
 also inconsistent. I suggest going to java.sun.com and reading their notes
 on how to create good API doc.

 My recommendation is to reject this patch as-is, and rewrite it to be
 better documentation. It is better to have to read the code than to be
 mislead by a function header, in my opinion. And if you're going to the
 trouble of putting in function header documentation, it should be good
 documentation.

-- 
Ticket URL: <http://trac.wordpress.org/ticket/3982#comment:2>
WordPress Trac <http://trac.wordpress.org/>
WordPress blogging software