Make WordPress Core

Opened 12 years ago

Closed 12 years ago

#21564 closed enhancement (fixed)

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

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

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 12 years ago.
21564-r21841.patch (4.7 KB) - added by bpetty 12 years ago.
21564.2.patch (4.4 KB) - added by SergeyBiryukov 12 years ago.

Download all attachments as: .zip

Change History (12)

#1 @nacin
12 years ago

  • Milestone changed from Awaiting Review to 3.5

@bpetty
12 years ago

#2 @bpetty
12 years ago

  • Keywords has-patch added; needs-patch removed

#3 @bpetty
12 years ago

  • Owner bpetty deleted
  • Status changed from new to assigned

#4 @scribu
12 years ago

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

#5 @nacin
12 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.

#6 @bpetty
12 years ago

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

#7 @SergeyBiryukov
12 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
12 years ago

Not a bad idea, either way works for me.

#9 @nacin
12 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.