[wp-hackers] Pushing Inline Documentation Patches

[Ryan Boren]

On 12/13/07, Jacob <wordpress at santosj.name> wrote:
> 1. Regarding the patch on ticket #4393 and author-template.php
> documentation, I went ahead and added @since information (based off of
> Ozh
> http://planetozh.com/projects/wordpress-functions-history/table_light.html)
> and cleaned up some of the PHPdoc tags. I haven't yet posted the patch,
> since I'm unsure whether I should reopen the old one (#4393) or create a
> new one. I'll most likely create a new ticket.

Either way.  Reopening is fine.

> 2. When creating an phpDocumentor site, third party libraries are
> included, which is incorrect behavior. I created a patch that excludes
> the external libraries (see #5443) by using file level phpdoc
> documentation and using a different package name. They will still be
> included, however the functions/classes will no longer be mixed with
> WordPress package functions/classes, which is the correct behavior.
>
> While I'm not sure it wouldn't cause problems, I think it would be an
> advantage to have the patch committed. If and when a WordPress
> phpDocumentor site is created.

We usually avoid changing third party files.  Maybe we can make an
exception for phpdoc.

> 3. I made a patch for post.php a long time ago (#3982) based off in part
> the previous patch that was made. As I didn't read too far into the
> ticket discussion, I failed to realize the problems inherit in the first
> patch, which also appears in mine. While I haven't yet gone back over
> the functions and made corrections to the patch, I would be super happy
> if the patch could be committed or some pointers made on how it can get
> to the point where it is ready to be committed.
>
> Also, since it has been a while, I'm not entirely sure the patch will
> commit. If not then, I can create a new patch based off a recent
> repository revision, when I get around to completing and fixing the errors.

Committed.  A few parts didn't apply so a follow on patch is needed.

> 4. Dude! Finished the Taxonomy API phpdoc style documentation (#4742).
> It would totally kick ass to close that ticket out.

Committed.

> 5. Is there any chance that the phpdoc documentation for wp-settings.php
> (#5211) or wp-includes/vars.php and wp-includes/version.php (also #5211)
> will get in? If not, then would it be wise to close the tickets as
> invalid (the patch for wp-settings.php might be stale anyway since the
> last one is based off of 6311) or won't fix? I would argue that the file
> level documentation makes it worth it for xref sites that include that
> along side the file name, as well as the advantage to phpDocumentor sites.

I'm fine with it.  Thoughts from others?