Changeset 27667 for trunk/src/wp-admin/includes/post.php

Timestamp:

03/24/2014 01:48:40 AM (11 years ago)

Author:

DrewAPicture

Message:

Inline documentation for hooks in wp-admin/includes/post.php.

Also moves the primary PHPDoc for the edit_posts_per_page hook to wp-admin/includes/post.php.

Props kpdesign for some cleanup.
Fixes #27431.

File:

• trunk/src/wp-admin/includes/post.php (modified) (17 diffs)

trunk/src/wp-admin/includes/post.php

@@ -275 +275 @@
 
         $attachment_data = isset( $post_data['attachments'][ $post_ID ] ) ? $post_data['attachments'][ $post_ID ] : array();
+
         /** This filter is documented in wp-admin/includes/media.php */
         $post_data = apply_filters( 'attachment_fields_to_save', $post_data, $attachment_data );
@@ -496 +497 @@
     }
 
+    /**
+     * Filter the default post content initially used in the "Write Post" form.
+     *
+     * @since 1.5.0
+     *
+     * @param string  $post_content Default post content.
+     * @param WP_Post $post         Post object.
+     */
     $post->post_content = apply_filters( 'default_content', $post_content, $post );
-    $post->post_title   = apply_filters( 'default_title',   $post_title, $post   );
+
+    /**
+     * Filter the default post title initially used in the "Write Post" form.
+     *
+     * @since 1.5.0
+     *
+     * @param string  $post_title Default post title.
+     * @param WP_Post $post       Post object.
+     */
+    $post->post_title = apply_filters( 'default_title', $post_title, $post );
+
+    /**
+     * Filter the default post excerpt initially used in the "Write Post" form.
+     *
+     * @since 1.5.0
+     *
+     * @param string  $post_excerpt Default post excerpt.
+     * @param WP_Post $post         Post object.
+     */
     $post->post_excerpt = apply_filters( 'default_excerpt', $post_excerpt, $post );
     $post->post_name = '';
@@ -866 +893 @@
         $posts_per_page = 20;
 
+    /**
+     * Filter the number of items per page to show for a specific 'per_page' type.
+     *
+     * The dynamic hook name, $per_page, refers to a hook name comprised of the post type,
+     * preceded by 'edit_', and succeeded by '_per_page', e.g. 'edit_$post_type_per_page'.
+     *
+     * Some examples of filter hooks generated here include: 'edit_attachment_per_page',
+     * 'edit_post_per_page', 'edit_page_per_page', etc.
+     *
+     * @since 3.0.0
+     *
+     * @param int $posts_per_page Number of posts to display per page for the given 'per_page'
+     *                            type. Default 20.
+     */
     $posts_per_page = apply_filters( $per_page, $posts_per_page );
+
+    /**
+     * Filter the number of posts displayed per page when specifically listing "posts".
+     *
+     * @since 2.8.0
+     *
+     * @param int    $per_page  Number of posts to be displayed. Default 20.
+     * @param string $post_type The post type.
+     */
     $posts_per_page = apply_filters( 'edit_posts_per_page', $posts_per_page, $post_type );
 
@@ -907 +957 @@
  *
  * @since 2.5.0
- * @uses apply_filters() Calls 'upload_per_page' on posts_per_page argument
  *
  * @param array|bool $q Array of query variables to use to build the query or false to use $_GET superglobal.
@@ -928 +977 @@
     if ( empty( $media_per_page ) || $media_per_page < 1 )
         $media_per_page = 20;
+
+    /**
+     * Filter the number of items to list per page when listing media items.
+     *
+     * @since 2.9.0
+     *
+     * @param int $media_per_page Number of media to list. Default 20.
+     */
     $q['posts_per_page'] = apply_filters( 'upload_per_page', $media_per_page );
 
@@ -967 +1024 @@
     }
 
+    /**
+     * Filter the postbox classes for a specific screen and screen ID combo.
+     *
+     * The dynamic portions of the hook name, $page, and $id, refer to
+     * the screen, and screen ID, respectively.
+     *
+     * @since 3.2.0
+     *
+     * @param array $classes An array of postbox classes.
+     */
     $classes = apply_filters( "postbox_classes_{$page}_{$id}", $classes );
     return implode( ' ', $classes );
@@ -1018 +1085 @@
         $uri = strrev( stristr( strrev( $uri ), '/' ) );
         $uri = untrailingslashit($uri);
+
+        /** This filter is documented in wp-admin/edit-tag-form.php */
         $uri = apply_filters( 'editable_slug', $uri );
         if ( !empty($uri) )
@@ -1024 +1093 @@
     }
 
-    $permalink = array($permalink, apply_filters('editable_slug', $post->post_name));
+    /** This filter is documented in wp-admin/edit-tag-form.php */
+    $permalink = array( $permalink, apply_filters( 'editable_slug', $post->post_name ) );
     $post->post_status = $original_status;
     $post->post_date = $original_date;
@@ -1068 +1138 @@
             $return .= "<span id='view-post-btn'><a href='$permalink' class='button button-small'>$view_post</a></span>\n";
 
-        $return = apply_filters('get_sample_permalink_html', $return, $id, $new_title, $new_slug);
+        /**
+         * Filter the sample permalink HTML markup.
+         *
+         * @since 2.9.0
+         *
+         * @param string      $return    Sample permalink HTML markup.
+         * @param int|WP_Post $id        Post object or ID.
+         * @param string      $new_title New sample permalink title.
+         * @param string      $new_slug  New sample permalink slug.
+         */
+        $return = apply_filters( 'get_sample_permalink_html', $return, $id, $new_title, $new_slug );
 
         return $return;
@@ -1100 +1180 @@
     }
 
-    $return = apply_filters('get_sample_permalink_html', $return, $id, $new_title, $new_slug);
+    /** This filter is documented in wp-admin/includes/post.php */
+    $return = apply_filters( 'get_sample_permalink_html', $return, $id, $new_title, $new_slug );
 
     return $return;
@@ -1138 +1219 @@
     }
 
+    /**
+     * Filter the admin post thumbnail HTML markup to return.
+     *
+     * @since 2.9.0
+     *
+     * @param string $content Admin post thumbnail HTML markup.
+     * @param int    $post_id Post ID.
+     */
     return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID );
 }
@@ -1160 +1249 @@
     $user = isset( $lock[1] ) ? $lock[1] : get_post_meta( $post->ID, '_edit_last', true );
 
+    /** This filter is documented in wp-admin/includes/ajax-actions.php */
     $time_window = apply_filters( 'wp_check_post_lock_window', 150 );
 
@@ -1204 +1294 @@
 
     if ( $user ) {
+
+        /**
+         * Filter whether to show the post locked dialog.
+         *
+         * Returning a falsey value to the filter will short-circuit displaying the dialog.
+         *
+         * @since 3.6.0
+         *
+         * @param bool         $display Whether to display the dialog. Default true.
+         * @param WP_User|bool $user    WP_User object on success, false otherwise.
+         */
         if ( ! apply_filters( 'show_post_locked_dialog', true, $post, $user ) )
             return;
@@ -1246 +1347 @@
         }
 
+        /** This filter is documented in wp-admin/includes/meta-boxes.php */
         $preview_link = apply_filters( 'preview_post_link', $preview_link );
+
+        /**
+         * Filter whether to allow the post lock to be overridden.
+         *
+         * Returning a falsey value to the filter will disable the ability
+         * to override the post lock.
+         *
+         * @since 3.6.0
+         *
+         * @param bool    $override Whether to allow overriding post locks. Default true.
+         * @param WP_Post $post     Post object.
+         * @param WP_User $user     User object.
+         */
         $override = apply_filters( 'override_post_lock', true, $post, $user );
         $tab_last = $override ? '' : ' wp-tab-last';
@@ -1260 +1375 @@
         ?>
         </p>
-        <?php do_action( 'post_locked_dialog', $post ); ?>
+        <?php
+        /**
+         * Fires inside the post locked dialog before the buttons are displayed.
+         *
+         * @since 3.6.0
+         *
+         * @param WP_Post $post Post object.
+         */
+        do_action( 'post_locked_dialog', $post );
+        ?>
         <p>
         <a class="button" href="<?php echo esc_url( $sendback ); ?>"><?php echo $sendback_text; ?></a>
@@ -1288 +1412 @@
             <span class="locked-saved hidden"><?php _e('Your latest changes were saved as a revision.'); ?></span>
             </p>
-            <?php do_action( 'post_lock_lost_dialog', $post ); ?>
+            <?php
+            /**
+             * Fires inside the dialog displayed when a user has lost the post lock.
+             *
+             * @since 3.6.0
+             *
+             * @param WP_Post $post Post object.
+             */
+            do_action( 'post_lock_lost_dialog', $post );
+            ?>
             <p><a class="button button-primary wp-tab-last" href="<?php echo esc_url( $sendback ); ?>"><?php echo $sendback_text; ?></a></p>
         </div>
@@ -1415 +1548 @@
 
     $url = add_query_arg( $query_args, get_permalink( $post->ID ) );
+
+    /** This filter is documented in wp-admin/includes/meta-boxes.php */
     return apply_filters( 'preview_post_link', $url );
 }