WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 7 years ago

Last modified 7 years ago

#25532 closed defect (bug) (fixed)

Hooks Docs: wp-admin/edit-tags.php

Reported by: pauldewouters Owned by: DrewAPicture
Milestone: 3.8 Priority: normal
Severity: normal Version:
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:

Description

Added hook documentation for the following actions/filters found in wp-admin/edit-tags.php:

  • Requires / Includes
  • term_updated_messages
  • 'after-' . $taxonomy . '-table', $taxonomy
  • add_category_form_pre
  • add_link_category_form_pre
  • add_tag_form_pre
  • $taxonomy . '_pre_add_form', $taxonomy
  • $taxonomy . '_term_new_form_tag'
  • taxonomy_parent_dropdown_args
  • add_tag_form_fields
  • `$taxonomy . '_add_form_fields', $taxonomy
  • edit_category_form
  • edit_link_category_form
  • add_tag_form
  • $taxonomy . '_add_form', $taxonomy

Attachments (4)

edit-tags-hook-docs.diff (6.2 KB) - added by pauldewouters 7 years ago.
edit-tags-hook-docs-rev1.diff (5.2 KB) - added by pauldewouters 7 years ago.
made suggested corrections
25532.diff (6.8 KB) - added by DrewAPicture 7 years ago.
25532.2.diff (8.0 KB) - added by DrewAPicture 7 years ago.
mark duplicates

Download all attachments as: .zip

Change History (14)

#1 @rzen
7 years ago

  • Cc brian@… added

Overall:

  • Can you remove the non-hook-related edits you've made? (e.g. lines 9-11, 131-134, 136-139, 260-262, 588-590)
  • @since tags should follow the 3-digit version notation, e.g. x.x.x
  • Instead of "Fires actions to be run..." phrase your short descriptions as "Fires before/after/during/...."
  • In your hash notations (e.g. lines 403, 415, 535, 547) you don't need to mention "Variables passed to the callback." because that is generic and applies to all hook params. Instead, a hash description should be unique to the hash it's describing.

'after-' . $taxonomy . '-table'

  • Missing @since tag
  • Missing @param tag

add_category_form_pre
add_link_category_form_pre
add_tag_form_pre

  • These three hooks were all deprecated at the introduction of {$taxonomy}_pre_add_form. Add @deprecated 3.0.0 Use {$taxonomy}_pre_add_form instead. to their docblocks, immediately after the @since tag (See PHPDoc Standards).
  • All three of their @param tags are incorrect, the data is being cast as an object, not an array, so we do not need the hash notation (which is a shame, because you wrote it quite well!).

edit_category_form
edit_link_category_form
add_tag_form

  • These three hooks were all deprecated at the introduction of {$taxonomy} _add_form . Add @deprecated 3.0.0 Use {$taxonomy} _add_form instead. to their docblocks, immediately after the @since tag (See PHPDoc Standards).
  • All three of their @param tags are incorrect, the data is being cast as an object, not an array, so we do not need the hash notation (which is a shame, because you wrote it quite well!).

#2 follow-up: @pauldewouters
7 years ago

thanks for the feedback, I have to say I wasn't sure at all about this.

I tried to replicate the comment styles from the Handbook, so that's why I reformatted the require/include comments to multiple lines.
http://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/#3-requires-and-includes

I'll make the other corrections as suggested. I did actually hesitate about adding comments for deprecated hooks. Now I know

#3 in reply to: ↑ 2 @kpdesign
7 years ago

Replying to pauldewouters:

I tried to replicate the comment styles from the Handbook, so that's why I reformatted the require/include comments to multiple lines.
http://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/#3-requires-and-includes

@pauldewouters:

The requires/includes will be documented during the functional docs review. The current hook docs effort focuses on documenting only the hooks.

We would like to keep the efforts separate patch-wise. By doing this, in the event a hook docs patch would need to be reverted for some reason, we wouldn't lose changes made to other doc blocks in the same patch.

Glad to see you joining in to help. :)

#4 @kpdesign
7 years ago

  • Keywords needs-patch added; has-patch removed
  • Owner set to rzen
  • Status changed from new to reviewing
  • Type changed from enhancement to defect (bug)

@pauldewouters
7 years ago

made suggested corrections

#5 follow-up: @pauldewouters
7 years ago

I made the changes, but not too sure what the @param tag should be for this: (object)array('parent' => 0)

#6 in reply to: ↑ 5 @DrewAPicture
7 years ago

  • Keywords has-patch added; needs-patch removed
  • Milestone changed from Awaiting Review to 3.8

Replying to pauldewouters:

I made the changes, but not too sure what the @param tag should be for this: (object)array('parent' => 0)

Maybe something like "An array of arguments, cast to an object."

We'll review your second patch and get back to you with some notes shortly.

@DrewAPicture
7 years ago

#7 @DrewAPicture
7 years ago

  • Keywords needs-testing added
  • Owner changed from rzen to DrewAPicture

25532.diff takes steps to cleanup the previous patch:

  • $taxonomy is a string, the taxonomy slug really, throughout the file, not an object.
  • Standardizes nomenclature for the "Add Term" screen for taxonomies
  • Adds a hash notation for the $dropdown_args parameter in the taxonomy_parent_dropdown_args filter
  • Standardizes affected lines with braces per the new coding standards change
  • Some coding standards spacing in the affected lines

As some small code changes were made in the latest patch, all of the above screens should be tested prior to commit.

@DrewAPicture
7 years ago

mark duplicates

#8 @DrewAPicture
7 years ago

  • Keywords commit added; needs-testing removed

Tested all hooks and screens with 25532.2.diff.

#9 @DrewAPicture
7 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 26274:

Inline documentation for hooks in wp-admin/edit-tags.php.

Props pauldewouters for the initial patch.
Fixes #25532.

#10 @DrewAPicture
7 years ago

In 26339:

Cleanup incorrect duplicate comments for hooks in wp-admin/edit-tag-form.php introduced in [26274].

Also corrects the @since version for {$taxonomy}_term_new_form_tag in wp-admin/edit-tags.php.

Props kpdesign. See #25532.

Note: See TracTickets for help on using tickets.