Make WordPress Core

Opened 17 years ago

Closed 16 years ago

#3982 closed enhancement (fixed)

PHPdoc effort for post.php

Reported by: m0n5t3r's profile m0n5t3r Owned by:
Milestone: 2.6 Priority: low
Severity: trivial Version:
Component: Optimization Keywords: phpdoc has-patch commit
Focuses: Cc:


documented post.php functions

Attachments (3)

post-phpdoc.diff (16.5 KB) - added by m0n5t3r 17 years ago.
post.php phpdoc take 1
post.phpdoc.diff (37.5 KB) - added by darkdragon 16 years ago.
Based off of the old patch and adds @since based off of Incomplete, but has param and return information
post.phpdoc.r8202.diff (15.7 KB) - added by jacobsantos 16 years ago.
Post phpdoc fixes for post.php based off of r8202

Download all attachments as: .zip

Change History (18)

17 years ago

post.php phpdoc take 1

#1 @m0n5t3r
17 years ago

  • Type changed from defect to enhancement

#2 @jhodgdon
17 years ago

  • Keywords developer-feedback added

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 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.

#3 @m0n5t3r
17 years ago

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)

#4 @ryan
16 years ago

  • Milestone changed from 2.3 to 2.4 (next)

#5 @ryan
16 years ago

  • Keywords phpdoc added

16 years ago

Based off of the old patch and adds @since based off of Incomplete, but has param and return information

#6 @darkdragon
16 years ago

  • Component changed from Administration to Optimization
  • Keywords commit added; needs-testing 2nd-opinion developer-feedback removed

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).

#7 @darkdragon
16 years ago


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

#8 @ryan
16 years ago

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

#9 @ryan
16 years ago

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.

#10 @darkdragon
16 years ago

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

#11 @darkdragon
16 years ago

  • Milestone changed from 2.4 to 2.5
  • Summary changed from post.php inline documentation to PHPdoc effort for post.php

#12 @westi
16 years ago

  • Keywords needs-patch added; has-patch commit removed

#13 @jacobsantos
16 years ago

  • Priority changed from normal to low
  • Severity changed from normal to trivial

16 years ago

Post phpdoc fixes for post.php based off of r8202

#14 @jacobsantos
16 years ago

  • Keywords has-patch commit added; needs-patch removed

#15 @ryan
16 years ago

  • Resolution set to fixed
  • Status changed from new to closed

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

Note: See TracTickets for help on using tickets.