WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 7 years ago

#21564 closed enhancement (fixed)

Avoid method redefinitions in docs by using unique method names for internal hooks

Reported by: bpetty Owned by: nacin
Milestone: 3.5 Priority: normal
Severity: normal Version: 3.4.1
Component: Administration Keywords: has-patch
Focuses: Cc:
PR Number:

Description

API documentation generators include all source files even if, in practice, only one of these files are included per request. Many core pages re-use the same method names for internal hooks which results in redefinitions for the docs, and resulting in missing documentation.

In general, it's good practice to keep these internal global method names as unique as possible anyway to avoid namespace (global scope) clashes since they aren't intended to be used as public API.

Patch coming soon...

Attachments (3)

21564.patch (7.5 KB) - added by bpetty 7 years ago.
21564-r21841.patch (4.7 KB) - added by bpetty 7 years ago.
21564.2.patch (4.4 KB) - added by SergeyBiryukov 7 years ago.

Download all attachments as: .zip

Change History (12)

#1 @nacin
7 years ago

  • Milestone changed from Awaiting Review to 3.5

@bpetty
7 years ago

#2 @bpetty
7 years ago

  • Keywords has-patch added; needs-patch removed

#3 @bpetty
7 years ago

  • Owner bpetty deleted
  • Status changed from new to assigned

#4 @scribu
7 years ago

  • Cc scribu added
  • Component changed from Inline Docs to Administration

#5 @nacin
7 years ago

I think we might need to keep display_header() in install.php, as that file can be running custom code via wp-content/install.php that could refer to it. Changing it in setup-config.php is simple enough, though. The rest looks fine.

@bpetty
7 years ago

#6 @bpetty
7 years ago

Updated patch leaves display_header() alone in wp-admin/install.php, but still changes the rest.

#7 @SergeyBiryukov
7 years ago

How about shorter names based on file names, e.g. options_reading_add_js()?

This would follow the same pattern as options_reading_blog_charset(), introduced in [21467].

#8 @bpetty
7 years ago

Not a bad idea, either way works for me.

#9 @nacin
7 years ago

  • Owner set to nacin
  • Resolution set to fixed
  • Status changed from assigned to closed

In [21856]:

Rename duplicately defined internal functions (add_js, display_header) for documentation purposes. props bpetty, fixes #21564.

Note: See TracTickets for help on using tickets.