WordPress.org

Make WordPress Core

Opened 5 months ago

Last modified 7 weeks ago

#26185 new defect (bug)

PHPDoc updates for /wp-includes/functions.php

Reported by: morganestes Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version: 3.7
Component: Bootstrap/Load Keywords: needs-patch
Focuses: docs Cc:

Description

Style fixes to add periods, arrange keywords in the correct order, and correct @param and @return values (adding descriptions when needed).

Attachments (2)

26185.diff (33.1 KB) - added by morganestes 5 months ago.
26185.1.diff (33.2 KB) - added by morganestes 8 weeks ago.
Refresh

Download all attachments as: .zip

Change History (9)

morganestes5 months ago

comment:1 morganestes4 months ago

  • Version 3.8 deleted

comment:2 morganestes4 months ago

  • Version set to trunk

comment:3 nacin3 months ago

  • Component changed from Inline Docs to Bootstrap/Load
  • Focuses docs added

comment:4 follow-up: jeremyfelt8 weeks ago

  • Keywords needs-refresh added

Looks good, @morganestes.

A couple notes from a read through:

  • docs for _http_build_query() seem to have some spacing issues around the params
  • similar spacing issues in docs for wp_filter_object_list()

morganestes8 weeks ago

Refresh

comment:5 in reply to: ↑ 4 morganestes8 weeks ago

  • Keywords 2nd-opinion added; needs-refresh removed
  • Version changed from trunk to 3.7

Replying to jeremyfelt:

  • docs for _http_build_query() seem to have some spacing issues around the params
  • similar spacing issues in docs for wp_filter_object_list()

Thanks for checking it out. I adjusted the spacing on those two doc blocks and added it as a .1 diff.

comment:6 follow-up: DrewAPicture7 weeks ago

  • Keywords needs-patch added; has-patch 2nd-opinion removed

Ideally, I'd like to avoid these huge patches in the future, instead focusing on specific change. It's tough to follow what's being changed and why, etc.

That said, here are some notes on 26185.1.diff:

Reference: Inline Documentation Standards

  • There should always be a new blank line between the short and long descriptions in a doc block
  • If you're going to add parameter descriptions, great. I'd prefer it if you consistently space-aligned the parts for parameters. Case in point, compare your docs changes for date_i18n() vs deprecated_file(). The style used with date_i18n() is definitely preferred :)
  • Please avoid adding new @global tags
  • @link, @see, etc. tags should always fall below the @since
  • If parameter description is wrapped, align with the first character of the first line with spaces
  • For hash notations (arrays), use a 4-space indent for each level of the array, not tabs

comment:7 in reply to: ↑ 6 morganestes7 weeks ago

Replying to DrewAPicture:

Ideally, I'd like to avoid these huge patches in the future, instead focusing on specific change. It's tough to follow what's being changed and why, etc.

Is it better to have a separate patch for each function/hook that I'm documenting?

I'll look at the overall structure again. I relied too much on my IDE autogenerating and formatting and it bit me. I'll go back and try again.

Note: See TracTickets for help on using tickets.