Clean up Inline Docs for revisions

[adamsilverstein]

Not much off here, mostly spacing, but thought I would take a sweep to refine my PHPDoc familiarity.

[DrewAPicture]

Both patches look good. The only thing is there should be no period on the short description for the file header in wp-admin/revision.php

[kpdesign]

Last line in ​wp-admin-revisions.diff:

* @param int    to       Optional, requirered if revision missing. The revision to compare to.

Should be:

* @param int    to       Optional, required if revision missing. The revision to compare to.

(typo fix)

[DrewAPicture]

Good catch Kim :)

[adamsilverstein]

Replying to kpdesign:

Last line in ​wp-admin-revisions.diff:

* @param int    to       Optional, requirered if revision missing. The revision to compare to.

Should be:

* @param int    to       Optional, required if revision missing. The revision to compare to.

(typo fix)

thanks!

[adamsilverstein]

Replying to DrewAPicture:

Both patches look good. The only thing is there should be no period on the short description for the file header in wp-admin/revision.php

ok, got it.

[SergeyBiryukov]

In 25419:

Inline documentation fixes and additions for wp-admin/revision.php and wp-admin/includes/revision.php.

props adamsilverstein.
see #25283.

[SergeyBiryukov]

Should _wp_post_revision_field_$field​ filter be documented as well?

[DrewAPicture]

We talked a little bit about "private" filters when writing the inline docs standards, though it was never really clear what the significance of prepending an underscore to a filter hook was actually supposed to be.

Short answer? I'd say yes, unless somebody 'in the know' provides a compelling argument not to.

[SergeyBiryukov]

In 25420:

Better alignment for wp_prepare_revisions_for_js() inline docs. see #25283.

[nacin]

Replying to DrewAPicture:

We talked a little bit about "private" filters when writing the inline docs standards, though it was never really clear what the significance of prepending an underscore to a filter hook was actually supposed to be.

Private filters should be documented with, at the very least, @access private, the same way documented filters should be documented with @deprecated.

That said: I don't think this hook is private. I think it just mimics the name of the related function _wp_post_revision_fields().

[DrewAPicture]

_wp_post_revision_field_$field filter hooks

[DrewAPicture]

@adamsilverstein: Mind taking a gander at 25283.diff​ to see if that's accurate or if it needs clarification?

[adamsilverstein]

Replying to DrewAPicture:

@adamsilverstein: Mind taking a gander at 25283.diff​ to see if that's accurate or if it needs clarification?

I think this looks good.

now that i'm looking i see more filters in here that need documenting like _wp_post_revision_fields() and wp_save_post_revision_check_for_changes - I will (try my best to) add docs for those and other in this file and post back here.

[DrewAPicture]

In 25587:

Inline documentation for hooks in wp-admin/includes/revision.php.

Fixes #25283.