Hook Docs: wp-admin/edit-form-advanced.php

[ericlewis]

I'm going to hold off on this until #25433 is resolved.

[DrewAPicture]

I'd rather have docs for some hooks than none. So maybe just skip the hook(s) in question in #25433.

[ericlewis]

attachment:25434.diff​ adds documentation for

• post_updated_messages
• dbx_post_advanced
• add_meta_boxes
• add_meta_boxes_{$post_type}
• do_meta_boxes
• post_edit_form_tag
• edit_form_top
• enter_title_here
• edit_form_after_title
• submitpage_box
• submitpost_box
• edit_page_form
• edit_form_advanced
• dbx_post_sidebar

[ericlewis]

attachment:25434.1.diff​ removes "the" articles from parameter descriptions.

[DrewAPicture]

Notes on 25434.1.diff​:
Overall:

• Looks like you've got the parameter types and variables switched in almost all of these. It should go:

  * @param type $variable Description.
  

post_updated_messages filter:

• Since the array keys are indexes, unfortunately it won't really be ideal to document the array of messages in hash notation. However, I would like to document (in a basic way) each of the indexes in the messages array, perhaps in a long description.

dbx_post_advanced hook:

• The short description seems incorrect, especially since the hook fires in the middle of meta boxes being added. What's the history of this hook? And what's with the naming scheme?

add_meta_boxes_{$post_type} hook:

• The dynamic part of the hook name should be spelled out in a long description.
• $post_type is part of the hook name, not a parameter

do_meta_boxes hook:

• s/After/Fires after
• Since this hook is fired three times in a row, the various contexts should be spelled out in a long description.

edit_form_top hook:

• "Fires at the."

enter_title_here filter:

• Specify the default placeholder text at the end of the parameter description.

submitpage_box, submitpost_box hooks:

• Based on the naming of the hook, we should probably mention that this hook firing as something to do with the submitpage|post box.

edit_page_form, edit_form_advanced hooks:

• Why only specify "after" 'normal' context when it's also before "advanced" context?

[ericlewis]

In attachment:25434.2.diff​,

• Fixed general parameter/type ordering.
• Fixed documentation for add_meta_boxes_{$post_type}, and added a long description of the dynamic bit.
• Added long description for do_meta_boxes to describe multiple firing for each meta box context.
• Added proper short desc for edit_form_top.
• Added default placeholder text for enter_title_here
• Mention relation of submitpage_box and submitpost_box to the submit meta box.
• Add more context to edit_page_form and edit_form_advanced

I'd like to check in about dbx_post_advanced and expected notation of post_updated_messages in our meeting.

[ericlewis]

In attachment:25434.3.diff​

• dbx_post_advanced gets deprecated and a better short description
• add a @see comment for the defaults of the post_updated_messages filter.

[DrewAPicture]

In 25819:

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

Props ericlewis.
Fixes #25434.