WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 7 months ago

Last modified 7 months ago

#16809 closed enhancement (fixed)

Inline Documentation Standard for Filters

Reported by: CharlesClarkson Owned by:
Milestone: 3.7 Priority: normal
Severity: normal Version: 3.1
Component: Inline Docs Keywords:
Focuses: Cc:

Description

I was hoping to get some insight on how to document filters as they are applied in a function. I'm referring to the use of the apply_filter() function inside a WordPress function, not for the use of the add_filter() function.

I thought to use something like one of these, but wanted some input on whether either was complete enough.

 * @uses apply_filters() for 'wp_admin_bar_class' providing 'WP_Admin_Bar' as the default class.

 * @note Adds the 'wp_admin_bar_class' filter to allow changing the default 'WP_Admin_Bar' class.

 * @link http://codex.wordpress.org/index.php?title=Plugin_API/Filter_Reference/wp_admin_bar_class

(Note: The link doesn't work yet. it is established from the Plugin API/Filter Reference)

I tend to look at inline docs as I use them (to update the codex and to research solutions) and that may not fit with other uses. I would rather not have to go back (too many times) because the my standard was useless to other users.

Thanks,

Change History (8)

comment:1 hakre3 years ago

Coding standards have no spec on how to document them so far.

The current usage isn't normlized either.

I suggest doing as it suits you while monitoring this ticket for the time being.

Last edited 3 years ago by hakre (previous) (diff)

comment:2 bananastalktome2 years ago

  • Cc bananastalktome@… added

comment:3 Rarst16 months ago

  • Cc contact@… added

comment:4 cais16 months ago

  • Cc edward.caissie@… added

comment:5 bueltge16 months ago

  • Cc frank@… added

comment:6 leewillis7715 months ago

  • Cc junk@… added

comment:7 DrewAPicture7 months ago

  • Milestone changed from Awaiting Review to 3.7
  • Resolution set to fixed
  • Severity changed from trivial to normal
  • Status changed from new to closed

A full set of inline documentation standards were developed in concert with the inline-docs push starting in 3.7. They can be found in the Core Contributor Handbook, here: http://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/

Note: See TracTickets for help on using tickets.