WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#25283 closed enhancement (fixed)

Clean up Inline Docs for revisions

Reported by: adamsilverstein Owned by: DrewAPicture
Milestone: 3.7 Priority: normal
Severity: normal Version:
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:

Description

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

Attachments (3)

wp-admin-revisions.diff (749 bytes) - added by adamsilverstein 5 years ago.
wp-admin-includes-revisions.diff (1.3 KB) - added by adamsilverstein 5 years ago.
25283.diff (1.4 KB) - added by DrewAPicture 5 years ago.
_wp_post_revision_field_$field filter hooks

Download all attachments as: .zip

Change History (20)

#1 @SergeyBiryukov
5 years ago

  • Milestone changed from Awaiting Review to 3.7

#2 @adamsilverstein
5 years ago

  • Keywords has-patch dev-feedback added

#3 follow-up: @DrewAPicture
5 years ago

  • Keywords commit added

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

#4 follow-up: @kpdesign
5 years ago

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)

#5 @DrewAPicture
5 years ago

  • Keywords commit removed

Good catch Kim :)

#6 in reply to: ↑ 4 @adamsilverstein
5 years ago

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!

#7 in reply to: ↑ 3 @adamsilverstein
5 years ago

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.

#8 @SergeyBiryukov
5 years ago

In 25419:

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

props adamsilverstein.
see #25283.

#9 @SergeyBiryukov
5 years ago

Should _wp_post_revision_field_$field filter be documented as well?

#10 follow-up: @DrewAPicture
5 years ago

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.

#11 @SergeyBiryukov
5 years ago

  • Keywords needs-patch added; has-patch dev-feedback removed

#12 @SergeyBiryukov
5 years ago

In 25420:

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

#13 in reply to: ↑ 10 @nacin
5 years ago

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
5 years ago

_wp_post_revision_field_$field filter hooks

#14 follow-up: @DrewAPicture
5 years ago

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

#15 in reply to: ↑ 14 @adamsilverstein
5 years ago

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.

#16 @DrewAPicture
5 years ago

  • Keywords has-patch commit added; needs-patch removed
  • Version trunk deleted

#17 @DrewAPicture
5 years ago

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

In 25587:

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

Fixes #25283.

Note: See TracTickets for help on using tickets.