[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  |  
--------------------------------------------------------------------+-------
Comment (by m0n5t3r):

 randomly ordered points:
  * I did try to get the return types and what the functions do right, but
 really the best one to document a function is the person who wrote it, as
 sometimes names are misleading (get_attachment_metadata seems to return an
 array with more than the file name, though)
  * the patch is here for review and correction, and possibly a good
 starting point for people who are far more familiar with the guts of
 wordpress than me
  * documenting 50 functions (that's the number I am getting from a quick
 grep on post.php) is a scary task if you do it from scratch; I think this
 one took me about 5 hours, and this with a lot of automation help from vim
 - getting function args, hook calls, etc;
  * inline documentation is far more useful for automated parsing (eclipse
 for instance shows the phpdoc info in some sort of a a menu, that's why I
 didn't start to write novels in there (partially, the other reasons being
 fatigue and laziness), that's the codex's job IMO
  * novel-style documentation would hurt more than no documentation at all
 (have you tried to read and make some sense out of a heavily commented
 java/c++/PEAR class?)

 (please pardon my possible lack of coherence and solid arguments, it's
 almost 5 AM here)

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