Make WordPress Core

Opened 11 years ago

Closed 11 years ago

#25658 closed enhancement (fixed)

Handle duplicate hooks in inline documentation

Reported by: nacin's profile nacin Owned by: nacin's profile nacin
Milestone: 3.7 Priority: normal
Severity: normal Version:
Component: Inline Docs Keywords: has-patch
Focuses: Cc:

Description

It looks like inline documentation efforts for hooks will continue well into 3.8, so rather than being able to rely on all hooks being documented and developer.wordpress.org being up and running, we should replace //duplicate_hook with something that is more human-parseable for release.

My suggestion: /** This hook is documented in {file} */. Alternatively, replace 'hook' with 'action' or 'filter', respectively.

Perhaps in the future, it would be a link to the hook's documentation on developer.wordpress.org instead (or in addition to).

There's only 40 duplicate hooks, and it's pretty easy to generate a list of them with something like ack -A 1 duplicate_hook, which will return the line that follows the match. From there, we could look for each hook and look at the line before it, until we return */, rather than the duplicate_hook comment. Then we would know where it is located. Or they could use a global project search in their editor. I imagine it would take someone about 20-30 minutes to do the whole thing?

Attachments (3)

25658.diff (17.4 KB) - added by DrewAPicture 11 years ago.
_action/_filter
25658-braces.diff (31.8 KB) - added by DrewAPicture 11 years ago.
with braces
25658-no-braces.diff (31.7 KB) - added by DrewAPicture 11 years ago.
without braces

Download all attachments as: .zip

Change History (10)

@DrewAPicture
11 years ago

_action/_filter

#1 @DrewAPicture
11 years ago

  • Keywords has-patch added

25658.diff changes //duplicate_hook references to their _action, and _filter counterparts. I agree that we should probably have a way to link them up with the original hooks, but that it may be better to wait on a longer-term solution until 3.8.

#2 @nacin
11 years ago

25658.diff​ changes duplicate_hook references to their _action, and _filter counterparts.

I meant that the string should become This action is documented in {file} or This filter is documented in {file}. Otherwise we should probably just remove them from the branch and leave them in trunk.

#3 @DrewAPicture
11 years ago

OK, I'll work on it.

#4 @jdgrimes
11 years ago

  • Cc jdg@… added

#5 @siobhyb
11 years ago

  • Cc siobhanbamber@… added

@DrewAPicture
11 years ago

with braces

@DrewAPicture
11 years ago

without braces

#6 @DrewAPicture
11 years ago

You know how I like to be literal, so I've attached two patches:

Didn't know if you needed the curly braces to more easily target the filename.

#7 @nacin
11 years ago

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

In 25868:

Spell out duplicate hook locations.

props DrewAPicture.
fixes #25658.

Note: See TracTickets for help on using tickets.