From ff4c82bd7bbdccc9407e1e367a9ef2919b454468 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Wed, 16 Oct 2013 22:58:21 +0000
Subject: [PATCH] Inline documentation for hooks in
 wp-admin/edit-form-advanced.php.

Props ericlewis.
Fixes #25434.


git-svn-id: https://develop.svn.wordpress.org/trunk@25819 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/edit-form-advanced.php | 176 ++++++++++++++++++++++++----
 1 file changed, 155 insertions(+), 21 deletions(-)

diff --git a/src/wp-admin/edit-form-advanced.php b/src/wp-admin/edit-form-advanced.php
index c11682def2..859d970254 100644
--- a/src/wp-admin/edit-form-advanced.php
+++ b/src/wp-admin/edit-form-advanced.php
@@ -32,6 +32,9 @@ if ( post_type_supports($post_type, 'editor') || post_type_supports($post_type,
 // Add the local autosave notice HTML
 add_action( 'admin_footer', '_local_storage_notice' );
 
+/*
+ * @todo Document the $messages array(s).
+ */
 $messages = array();
 $messages['post'] = array(
 	 0 => '', // Unused. Messages start at index 1.
@@ -64,6 +67,13 @@ $messages['page'] = array(
 );
 $messages['attachment'] = array_fill( 1, 10, __( 'Media attachment updated.' ) ); // Hack, for now.
 
+/**
+ * Filter the post updated messages.
+ *
+ * @since 3.0.0
+ *
+ * @param array $messages Post updated messages. For defaults @see $messages declarations above.
+ */
 $messages = apply_filters( 'post_updated_messages', $messages );
 
 $message = false;
@@ -172,7 +182,16 @@ if ( post_type_supports($post_type, 'trackbacks') )
 if ( post_type_supports($post_type, 'custom-fields') )
 	add_meta_box('postcustom', __('Custom Fields'), 'post_custom_meta_box', null, 'normal', 'core');
 
-do_action('dbx_post_advanced', $post);
+/**
+ * Fires in the middle of built-in meta box registration.
+ *
+ * @since 2.1.0
+ * @deprecated 3.7.0 Use 'add_meta_boxes' instead.
+ *
+ * @param WP_Post $post Post object.
+ */
+do_action( 'dbx_post_advanced', $post );
+
 if ( post_type_supports($post_type, 'comments') )
 	add_meta_box('commentstatusdiv', __('Discussion'), 'post_comment_status_meta_box', null, 'normal', 'core');
 
@@ -187,12 +206,43 @@ if ( post_type_supports($post_type, 'author') ) {
 		add_meta_box('authordiv', __('Author'), 'post_author_meta_box', null, 'normal', 'core');
 }
 
-do_action('add_meta_boxes', $post_type, $post);
-do_action('add_meta_boxes_' . $post_type, $post);
+/**
+ * Fires after all built-in meta boxes have been added.
+ *
+ * @since 3.0.0
+ *
+ * @param string  $post_type Post type.
+ * @param WP_Post $post      Post object.
+ */
+do_action( 'add_meta_boxes', $post_type, $post );
 
-do_action('do_meta_boxes', $post_type, 'normal', $post);
-do_action('do_meta_boxes', $post_type, 'advanced', $post);
-do_action('do_meta_boxes', $post_type, 'side', $post);
+/**
+ * Fires after all built-in meta boxes have been added, contextually for the given post type.
+ *
+ * The dynamic portion of the hook, $post_type, refers to the post type of the post.
+ *
+ * @since 3.0.0
+ *
+ * @param WP_Post $post Post object.
+ */
+do_action( 'add_meta_boxes_' . $post_type, $post );
+
+/**
+ * Fires after meta boxes have been added.
+ *
+ * Fires once for each of the default meta box contexts: normal, advanced, and side.
+ *
+ * @since 3.0.0
+ *
+ * @param string  $post_type Post type of the post.
+ * @param string  $context   string  Meta box context.
+ * @param WP_Post $post      Post object.
+ */
+do_action( 'do_meta_boxes', $post_type, 'normal', $post );
+//duplicate_hook
+do_action( 'do_meta_boxes', $post_type, 'advanced', $post );
+//duplicate_hook
+do_action( 'do_meta_boxes', $post_type, 'side', $post );
 
 add_screen_option('layout_columns', array('max' => 2, 'default' => 2) );
 
@@ -326,8 +376,16 @@ if ( isset( $post_new_file ) && current_user_can( $post_type_object->cap->create
 	<span class="hide-if-no-sessionstorage"><?php _e( 'We&#8217;re backing up this post in your browser, just in case.' ); ?></span>
 	</p>
 </div>
-
-<form name="post" action="post.php" method="post" id="post"<?php do_action('post_edit_form_tag', $post); ?>>
+<?php
+/**
+ * Fires inside the post editor <form> tag.
+ *
+ * @since 3.0.0
+ *
+ * @param WP_Post $post Post object.
+ */
+?>
+<form name="post" action="post.php" method="post" id="post"<?php do_action( 'post_edit_form_tag', $post ); ?>>
 <?php wp_nonce_field($nonce_action); ?>
 <input type="hidden" id="user-id" name="user_ID" value="<?php echo (int) $user_ID ?>" />
 <input type="hidden" id="hiddenaction" name="action" value="<?php echo esc_attr( $form_action ) ?>" />
@@ -350,7 +408,17 @@ wp_nonce_field( 'meta-box-order', 'meta-box-order-nonce', false );
 wp_nonce_field( 'closedpostboxes', 'closedpostboxesnonce', false );
 ?>
 
-<?php do_action( 'edit_form_top', $post ); ?>
+<?php
+/**
+ * Fires at the beginning of the edit form.
+ *
+ * At this point, the required hidden fields and nonces have already been output.
+ *
+ * @since 3.7.0
+ *
+ * @param WP_Post $post Post object.
+ */
+do_action( 'edit_form_top', $post ); ?>
 
 <div id="poststuff">
 <div id="post-body" class="metabox-holder columns-<?php echo 1 == get_current_screen()->get_columns() ? '1' : '2'; ?>">
@@ -359,6 +427,16 @@ wp_nonce_field( 'closedpostboxes', 'closedpostboxesnonce', false );
 <?php if ( post_type_supports($post_type, 'title') ) { ?>
 <div id="titlediv">
 <div id="titlewrap">
+	<?php
+	/**
+	 * Filter the title field placeholder text.
+	 *
+	 * @since 3.1.0
+	 *
+	 * @param string  $text Placeholder text. Default 'Enter title here'.
+	 * @param WP_Post $post Post object.
+	 */
+	?>
 	<label class="screen-reader-text" id="title-prompt-text" for="title"><?php echo apply_filters( 'enter_title_here', __( 'Enter title here' ), $post ); ?></label>
 	<input type="text" name="post_title" size="30" value="<?php echo esc_attr( htmlspecialchars( $post->post_title ) ); ?>" id="title" autocomplete="off" />
 </div>
@@ -389,7 +467,13 @@ wp_nonce_field( 'samplepermalink', 'samplepermalinknonce', false );
 </div><!-- /titlediv -->
 <?php
 }
-
+/**
+ * Fires after the title field.
+ *
+ * @since 3.5.0
+ *
+ * @param WP_Post $post Post object.
+ */
 do_action( 'edit_form_after_title', $post );
 
 if ( post_type_supports($post_type, 'editor') ) {
@@ -420,7 +504,13 @@ if ( post_type_supports($post_type, 'editor') ) {
 
 </div>
 <?php }
-
+/**
+ * Fires after the content editor.
+ *
+ * @since 3.5.0
+ *
+ * @param WP_Post $post Post object.
+ */
 do_action( 'edit_form_after_editor', $post );
 ?>
 </div><!-- /post-body-content -->
@@ -428,10 +518,31 @@ do_action( 'edit_form_after_editor', $post );
 <div id="postbox-container-1" class="postbox-container">
 <?php
 
-if ( 'page' == $post_type )
-	do_action('submitpage_box', $post);
-else
-	do_action('submitpost_box', $post);
+if ( 'page' == $post_type ) {
+	/**
+	 * Fires before meta boxes with 'side' context are output for the 'page' post type.
+	 *
+	 * The submitpage box is a meta box with 'side' context, so this hook fires just before it is output.
+	 *
+	 * @since 2.5.0
+	 *
+	 * @param WP_Post $post Post object.
+	 */
+	do_action( 'submitpage_box', $post );
+}
+else {
+	/**
+	 * Fires before meta boxes with 'side' context are output for all post types other than 'page'.
+	 *
+	 * The submitpost box is a meta box with 'side' context, so this hook fires just before it is output.
+	 *
+	 * @since 2.5.0
+	 *
+	 * @param WP_Post $post Post object.
+	 */
+	do_action( 'submitpost_box', $post );
+}
+
 
 do_meta_boxes($post_type, 'side', $post);
 
@@ -442,18 +553,41 @@ do_meta_boxes($post_type, 'side', $post);
 
 do_meta_boxes(null, 'normal', $post);
 
-if ( 'page' == $post_type )
-	do_action('edit_page_form', $post);
-else
-	do_action('edit_form_advanced', $post);
+if ( 'page' == $post_type ) {
+	/**
+	 * Fires after 'normal' context meta boxes have been output for the 'page' post type.
+	 *
+	 * @since 1.5.2
+	 *
+	 * @param WP_Post $post Post object.
+	 */
+	do_action( 'edit_page_form', $post );
+}
+else {
+	/**
+	 * Fires after 'normal' context meta boxes have been output for all post types other than 'page'.
+	 *
+	 * @since 1.5.2
+	 *
+	 * @param WP_Post $post Post object.
+	 */
+	do_action( 'edit_form_advanced', $post );
+}
+
 
 do_meta_boxes(null, 'advanced', $post);
 
 ?>
 </div>
 <?php
-
-do_action('dbx_post_sidebar', $post);
+/**
+ * Fires after all meta box sections have been output, before the closing #post-body div.
+ *
+ * @since 2.1.0
+ *
+ * @param WP_Post $post Post object.
+ */
+do_action( 'dbx_post_sidebar', $post );
 
 ?>
 </div><!-- /post-body -->