PHPdoc effort for post.php

post.php phpdoc take 1

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.

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)

Based off of the old patch and adds @since based off of http://planetozh.com/projects/wordpress-functions-history/table_light.html. Incomplete, but has param and return information

Another five hours spent on documenting this file. Would have been more if not spending some time moving the old patch and getting it to work with the current commit revision.

Massively incomplete, lacking long descriptions and descriptions of some parameters and most return types. A good running start. I'll go over the documentation some time this week, after I pay some more attention to taxonomy.php (which is almost done) and widgets.php (not even close to being done, but I'll most likely at least document the parameters and return values).

Bump.

Can this patch still go in? Let me know if it won't commit and I'll submit an updated patch.

(In [6379]) post phpdoc from m0n5t3r and darkdragon. see #3982

A few parts of the patch didn't apply cleanly.

Hunk #17 FAILED at 617.
Hunk #28 FAILED at 1189.
Hunk #32 FAILED at 1314.
Hunk #44 FAILED at 1742.

Thanks. I will look at it today and fix it.

Post phpdoc fixes for post.php based off of r8202

(In [8203]) phpdoc updates for post.php from jacobsantos. fixes #3982