WordPress.org

Make WordPress Core

Opened 8 years ago

Closed 7 years ago

#3982 closed enhancement (fixed)

PHPdoc effort for post.php

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

Description

documented post.php functions

Attachments (3)

post-phpdoc.diff (16.5 KB) - added by m0n5t3r 8 years ago.
post.php phpdoc take 1
post.phpdoc.diff (37.5 KB) - added by darkdragon 7 years ago.
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
post.phpdoc.r8202.diff (15.7 KB) - added by jacobsantos 7 years ago.
Post phpdoc fixes for post.php based off of r8202

Download all attachments as: .zip

Change History (18)

@m0n5t3r8 years ago

post.php phpdoc take 1

comment:1 @m0n5t3r8 years ago

  • Type changed from defect to enhancement

comment:2 @jhodgdon8 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 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.

comment:3 @m0n5t3r8 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)

comment:4 @ryan8 years ago

  • Milestone changed from 2.3 to 2.4 (next)

comment:5 @ryan7 years ago

  • Keywords phpdoc added

@darkdragon7 years ago

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

comment:6 @darkdragon7 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).

comment:7 @darkdragon7 years ago

Bump.

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

comment:8 @ryan7 years ago

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

comment:9 @ryan7 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.

comment:10 @darkdragon7 years ago

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

comment:11 @darkdragon7 years ago

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

comment:12 @westi7 years ago

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

comment:13 @jacobsantos7 years ago

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

@jacobsantos7 years ago

Post phpdoc fixes for post.php based off of r8202

comment:14 @jacobsantos7 years ago

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

comment:15 @ryan7 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.