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

[pauldewouters]

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

[rzen]

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!).

[pauldewouters]

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

[kpdesign]

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. :)

[pauldewouters]

made suggested corrections

[pauldewouters]

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

[DrewAPicture]

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]

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]

mark duplicates

[DrewAPicture]

Tested all hooks and screens with 25532.2.diff​.

[DrewAPicture]

In 26274:

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

Props pauldewouters for the initial patch.
Fixes #25532.

[DrewAPicture]

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.