From 3086f189ccba742b9c3a0d4ae549d6f46dfb70a9 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Wed, 8 Jan 2014 04:06:01 +0000
Subject: [PATCH] Inline documentation for hooks in
 wp-admin/includes/meta-boxes.php.

Props SpencerFinnell for the initial patch.
Fixes #26092.


git-svn-id: https://develop.svn.wordpress.org/trunk@26918 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/meta-boxes.php | 73 +++++++++++++++++++++++++---
 1 file changed, 66 insertions(+), 7 deletions(-)

diff --git a/src/wp-admin/includes/meta-boxes.php b/src/wp-admin/includes/meta-boxes.php
index e77c9ecc4f..01ac430433 100644
--- a/src/wp-admin/includes/meta-boxes.php
+++ b/src/wp-admin/includes/meta-boxes.php
@@ -42,6 +42,13 @@ if ( 'publish' == $post->post_status ) {
 	$preview_button = __( 'Preview Changes' );
 } else {
 	$preview_link = set_url_scheme( get_permalink( $post->ID ) );
+	/**
+	 * Filter the URI of a post preview in the post submit box.
+	 *
+	 * @since 2.0.5
+	 *
+	 * @param string $preview_link URI the user will be directed to for a post preview.
+	 */
 	$preview_link = esc_url( apply_filters( 'preview_post_link', add_query_arg( 'preview', 'true', $preview_link ) ) );
 	$preview_button = __( 'Preview' );
 }
@@ -198,13 +205,27 @@ if ( $can_publish ) : // Contributors don't get to choose the date of publish ?>
 </div><?php // /misc-pub-section ?>
 <?php endif; ?>
 
-<?php do_action('post_submitbox_misc_actions'); ?>
+<?php
+/**
+ * Fires after the post time/date setting in the Publish meta box.
+ *
+ * @since 2.9.0
+ */
+do_action( 'post_submitbox_misc_actions' );
+?>
 </div>
 <div class="clear"></div>
 </div>
 
 <div id="major-publishing-actions">
-<?php do_action('post_submitbox_start'); ?>
+<?php
+/**
+ * Fires at the beginning of the publishing actions section of the Publish meta box.
+ *
+ * @since 2.7.0
+ */
+do_action( 'post_submitbox_start' );
+?>
 <div id="delete-action">
 <?php
 if ( current_user_can( "delete_post", $post->ID ) ) {
@@ -282,7 +303,15 @@ function attachment_submit_meta_box( $post ) {
 		<span id="timestamp"><?php printf($stamp, $date); ?></span>
 	</div><!-- .misc-pub-section -->
 
-	<?php do_action('attachment_submitbox_misc_actions'); ?>
+	<?php
+	/**
+	 * Fires after the 'Uploaded on' section of the Save meta box
+	 * in the attachment editing screen.
+	 *
+	 * @since 3.5.0
+	 */
+	do_action( 'attachment_submitbox_misc_actions' );
+	?>
 </div><!-- #misc-publishing-actions -->
 <div class="clear"></div>
 </div><!-- #minor-publishing -->
@@ -525,7 +554,16 @@ function post_comment_status_meta_box($post) {
 <p class="meta-options">
 	<label for="comment_status" class="selectit"><input name="comment_status" type="checkbox" id="comment_status" value="open" <?php checked($post->comment_status, 'open'); ?> /> <?php _e( 'Allow comments.' ) ?></label><br />
 	<label for="ping_status" class="selectit"><input name="ping_status" type="checkbox" id="ping_status" value="open" <?php checked($post->ping_status, 'open'); ?> /> <?php printf( __( 'Allow <a href="%s" target="_blank">trackbacks and pingbacks</a> on this page.' ), __( 'http://codex.wordpress.org/Introduction_to_Blogging#Managing_Comments' ) ); ?></label>
-	<?php do_action('post_comment_status_meta_box-options', $post); ?>
+	<?php
+	/**
+	 * Fires at the end of the Discussion meta box on the post editing screen.
+	 *
+	 * @since 3.1.0
+	 *
+	 * @param WP_Post $post WP_Post object of the current post.
+	 */
+	do_action( 'post_comment_status_meta_box-options', $post );
+	?>
 </p>
 <?php
 }
@@ -588,8 +626,9 @@ function post_comment_meta_box( $post ) {
  * @param object $post
  */
 function post_slug_meta_box($post) {
+/** This filter is documented in wp-admin/edit-tag-form.php */
 ?>
-<label class="screen-reader-text" for="post_name"><?php _e('Slug') ?></label><input name="post_name" type="text" size="13" id="post_name" value="<?php echo esc_attr( apply_filters('editable_slug', $post->post_name) ); ?>" />
+<label class="screen-reader-text" for="post_name"><?php _e('Slug') ?></label><input name="post_name" type="text" size="13" id="post_name" value="<?php echo esc_attr( apply_filters( 'editable_slug', $post->post_name ) ); ?>" />
 <?php
 }
 
@@ -646,6 +685,16 @@ function page_attributes_meta_box($post) {
 			'echo'             => 0,
 		);
 
+		/**
+		 * Filter the arguments used to generate a Pages drop-down element.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @see wp_dropdown_pages()
+		 *
+		 * @param array   $dropdown_args Array of arguments used to generate the pages drop-down.
+		 * @param WP_Post $post          The current WP_Post object.
+		 */
 		$dropdown_args = apply_filters( 'page_attributes_dropdown_pages_args', $dropdown_args, $post );
 		$pages = wp_dropdown_pages( $dropdown_args );
 		if ( ! empty($pages) ) {
@@ -710,7 +759,10 @@ function link_submit_meta_box($link) {
 </div>
 
 <div id="major-publishing-actions">
-<?php do_action('post_submitbox_start'); ?>
+<?php
+/** This action is documented in wp-admin/includes/meta-boxes.php */
+do_action( 'post_submitbox_start' );
+?>
 <div id="delete-action">
 <?php
 if ( !empty($_GET['action']) && 'edit' == $_GET['action'] && current_user_can('manage_links') ) { ?>
@@ -727,7 +779,14 @@ if ( !empty($_GET['action']) && 'edit' == $_GET['action'] && current_user_can('m
 </div>
 <div class="clear"></div>
 </div>
-<?php do_action('submitlink_box'); ?>
+<?php
+/**
+ * Fires at the end of the Publish box in the Link editing screen.
+ *
+ * @since 2.5.0
+ */
+do_action( 'submitlink_box' );
+?>
 <div class="clear"></div>
 </div>
 <?php