WordPress.org
Get WordPress

Make WordPress Core

Changeset 29094


Ignore:
Timestamp:
07/11/2014 11:15:49 AM (10 years ago)
Author:
DrewAPicture
Message:

General inline documentation improvements in wp-includes/post.php.

Final-run. Fixes #25412.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r29093 r29094  
    47234723
    47244724/**
    4725  * Trashes or deletes an attachment.
     4725 * Trash or delete an attachment.
    47264726 *
    47274727 * When an attachment is permanently deleted, the file will also be removed.
    … …  
    47334733 *
    47344734 * @since 2.0.0
    4735  * @uses $wpdb
    4736  *
    4737  * @param int $post_id Attachment ID.
    4738  * @param bool $force_delete Whether to bypass trash and force deletion. Defaults to false.
     4735 *
     4736 * @global wpdb $wpdb WordPress database access abstraction object.
     4737 *
     4738 * @param int  $post_id      Attachment ID.
     4739 * @param bool $force_delete Optional. Whether to bypass trash and force deletion.
     4740 *                           Default false.
    47394741 * @return mixed False on failure. Post data on success.
    47404742 */
    … …  
    48014803
    48024804    if ( ! empty($meta['thumb']) ) {
    4803         // Don't delete the thumb if another attachment uses it
     4805        // Don't delete the thumb if another attachment uses it.
    48044806        if (! $wpdb->get_row( $wpdb->prepare( "SELECT meta_id FROM $wpdb->postmeta WHERE meta_key = '_wp_attachment_metadata' AND meta_value LIKE %s AND post_id <> %d", '%' . $wpdb->esc_like( $meta['thumb'] ) . '%', $post_id)) ) {
    48054807            $thumbfile = str_replace(basename($file), $meta['thumb'], $file);
    … …  
    48104812    }
    48114813
    4812     // remove intermediate and backup images if there are any
     4814    // Remove intermediate and backup images if there are any.
    48134815    foreach ( $intermediate_sizes as $intermediate ) {
    48144816        /** This filter is documented in wp-admin/custom-header.php */
    … …  
    48424844 * @since 2.1.0
    48434845 *
    4844  * @param int $post_id Attachment ID. Default 0.
    4845  * @param bool $unfiltered Optional, default is false. If true, filters are not run.
     4846 * @param int  $post_id    Attachment ID. Default 0.
     4847 * @param bool $unfiltered Optional. If true, filters are not run. Default false.
    48464848 * @return string|bool Attachment meta field. False on failure.
    48474849 */
    … …  
    48734875 * @since 2.1.0
    48744876 *
    4875  * @param int $post_id Attachment ID.
    4876  * @param array $data Attachment data.
    4877  * @return int
     4877 * @param int   $post_id Attachment ID.
     4878 * @param array $data    Attachment data.
     4879 * @return int|bool False if $post is invalid.
    48784880 */
    48794881function wp_update_attachment_metadata( $post_id, $data ) {
    … …  
    49024904 *
    49034905 * @param int $post_id Optional. Attachment ID. Default 0.
    4904  * @return string
     4906 * @return string|bool Attachment URL, otherwise false.
    49054907 */
    49064908function wp_get_attachment_url( $post_id = 0 ) {
    … …  
    49134915
    49144916    $url = '';
    4915     if ( $file = get_post_meta( $post->ID, '_wp_attached_file', true) ) { //Get attached file
    4916         if ( ($uploads = wp_upload_dir()) && false === $uploads['error'] ) { //Get upload directory
    4917             if ( 0 === strpos($file, $uploads['basedir']) ) //Check that the upload base exists in the file location
    4918                 $url = str_replace($uploads['basedir'], $uploads['baseurl'], $file); //replace file location with url location
    4919             elseif ( false !== strpos($file, 'wp-content/uploads') )
     4917    // Get attached file.
     4918    if ( $file = get_post_meta( $post->ID, '_wp_attached_file', true) ) {
     4919        // Get upload directory.
     4920        if ( ($uploads = wp_upload_dir()) && false === $uploads['error'] ) {
     4921            // Check that the upload base exists in the file location.
     4922            if ( 0 === strpos( $file, $uploads['basedir'] ) ) {
     4923                // Replace file location with url location.
     4924                $url = str_replace($uploads['basedir'], $uploads['baseurl'], $file);
     4925            } elseif ( false !== strpos($file, 'wp-content/uploads') ) {
    49204926                $url = $uploads['baseurl'] . substr( $file, strpos($file, 'wp-content/uploads') + 18 );
    4921             else
    4922                 $url = $uploads['baseurl'] . "/$file"; //Its a newly uploaded file, therefor $file is relative to the basedir.
    4923         }
    4924     }
    4925 
    4926     if ( empty($url) ) //If any of the above options failed, Fallback on the GUID as used pre-2.7, not recommended to rely upon this.
     4927            } else {
     4928                // It's a newly-uploaded file, therefore $file is relative to the basedir.
     4929                $url = $uploads['baseurl'] . "/$file";
     4930            }
     4931        }
     4932    }
     4933
     4934    /*
     4935     * If any of the above options failed, Fallback on the GUID as used pre-2.7,
     4936     * not recommended to rely upon this.
     4937     */
     4938    if ( empty($url) ) {
    49274939        $url = get_the_guid( $post->ID );
     4940    }
    49284941
    49294942    /**
    … …  
    50405053 *
    50415054 * @param string|int $mime MIME type or attachment ID.
    5042  * @return string|bool
     5055 * @return string|bool Icon, false otherwise.
    50435056 */
    50445057function wp_mime_type_icon( $mime = 0 ) {
    … …  
    51195132        }
    51205133
    5121         // Icon basename - extension = MIME wildcard
     5134        // Icon basename - extension = MIME wildcard.
    51225135        foreach ( $icon_files as $file => $uri )
    51235136            $types[ preg_replace('/^([^.]*).*$/', '$1', basename($file)) ] =& $icon_files[$file];
    … …  
    51565169
    51575170/**
    5158  * Checked for changed slugs for published post objects and save the old slug.
     5171 * Check for changed slugs for published post objects and save the old slug.
    51595172 *
    51605173 * The function is used when a post object of any type is updated,
    … …  
    51705183 * @since 2.1.0
    51715184 *
    5172  * @param int $post_id Post ID.
    5173  * @param object $post The Post Object
    5174  * @param object $post_before The Previous Post Object
     5185 * @param int     $post_id    Post ID.
     5186 * @param WP_Post $post        The Post Object
     5187 * @param WP_Post $post_before The Previous Post Object
    51755188 * @return int Same as $post_id
    51765189 */
    5177 function wp_check_for_changed_slugs($post_id, $post, $post_before) {
    5178     // dont bother if it hasnt changed
     5190function wp_check_for_changed_slugs( $post_id, $post, $post_before ) {
     5191    // Don't bother if it hasnt changed.
    51795192    if ( $post->post_name == $post_before->post_name )
    51805193        return;
    51815194
    5182     // we're only concerned with published, non-hierarchical objects
     5195    // We're only concerned with published, non-hierarchical objects.
    51835196    if ( $post->post_status != 'publish' || is_post_type_hierarchical( $post->post_type ) )
    51845197        return;
    … …  
    51865199    $old_slugs = (array) get_post_meta($post_id, '_wp_old_slug');
    51875200
    5188     // if we haven't added this old slug before, add it now
     5201    // If we haven't added this old slug before, add it now.
    51895202    if ( !empty( $post_before->post_name ) && !in_array($post_before->post_name, $old_slugs) )
    51905203        add_post_meta($post_id, '_wp_old_slug', $post_before->post_name);
    51915204
    5192     // if the new slug was used previously, delete it from the list
     5205    // If the new slug was used previously, delete it from the list.
    51935206    if ( in_array($post->post_name, $old_slugs) )
    51945207        delete_post_meta($post_id, '_wp_old_slug', $post->post_name);
    … …  
    52055218 * @since 2.2.0
    52065219 *
    5207  * @param string $post_type currently only supports 'post' or 'page'.
     5220 * @param string $post_type Post type. Currently only supports 'post' or 'page'.
    52085221 * @return string SQL code that can be added to a where clause.
    52095222 */
    … …  
    52155228 * Retrieve the post SQL based on capability, author, and type.
    52165229 *
     5230 * @since 3.0.0
     5231 *
    52175232 * @see get_private_posts_cap_sql()
    52185233 *
    5219  * @since 3.0.0
    5220  * @param string $post_type Post type.
    5221  * @param bool $full Optional. Returns a full WHERE statement instead of just an 'andalso' term.
    5222  * @param int $post_author Optional. Query posts having a single author ID.
    5223  * @param bool $public_only Optional. Only return public posts. Skips cap checks for $current_user.  Default is false.
     5234 * @param string $post_type   Post type.
     5235 * @param bool   $full        Optional. Returns a full WHERE statement instead of just
     5236 *                            an 'andalso' term. Default true.
     5237 * @param int    $post_author Optional. Query posts having a single author ID. Default null.
     5238 * @param bool   $public_only Optional. Only return public posts. Skips cap checks for
     5239 *                            $current_user.  Default false.
    52245240 * @return string SQL WHERE code that can be added to a query.
    52255241 */
    … …  
    52275243    global $wpdb;
    52285244
    5229     // Private posts
     5245    // Private posts.
    52305246    $post_type_obj = get_post_type_object( $post_type );
    52315247    if ( ! $post_type_obj )
    … …  
    52875303 * @since 0.71
    52885304 *
    5289  * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
     5305 * @param string $timezone The location to get the time. Accepts 'gmt', 'blog',
     5306 *                         or 'server'. Default 'server'.
    52905307 * @return string The date of the last post.
    52915308 */
    5292 function get_lastpostdate($timezone = 'server') {
     5309function get_lastpostdate( $timezone = 'server' ) {
    52935310    /**
    52945311     * Filter the date the last post was published.
    … …  
    53125329 * @since 1.2.0
    53135330 *
    5314  * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
     5331 * @param string $timezone The location to get the time. Accepts 'gmt', 'blog', or 'server'.
     5332 *                         Default 'server'.
    53155333 * @return string The date the post was last modified.
    53165334 */
    5317 function get_lastpostmodified($timezone = 'server') {
     5335function get_lastpostmodified( $timezone = 'server' ) {
    53185336    $lastpostmodified = _get_last_post_time( $timezone, 'modified' );
    53195337
    … …  
    53395357 * @since 3.1.0
    53405358 *
    5341  * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
     5359 * @param string $timezone The location to get the time. Accepts 'gmt', 'blog', or 'server'.
    53425360 * @param string $field Field to check. Can be 'date' or 'modified'.
    53435361 * @return string The date.
    … …  
    53865404 * @since 1.5.1
    53875405 *
    5388  * @param array $posts Array of post objects
     5406 * @param array $posts Array of post objects, passed by reference.
    53895407 */
    53905408function update_post_cache( &$posts ) {
    … …  
    54065424 *
    54075425 * @since 2.0.0
     5426 *
     5427 * @global wpdb $wpdb WordPress database access abstraction object.
    54085428 *
    54095429 * @param int|WP_Post $post Post ID or post object to remove from the cache.
    … …  
    54575477 * @since 1.5.0
    54585478 *
    5459  * @uses update_post_cache()
    5460  * @uses update_object_term_cache()
    5461  * @uses update_postmeta_cache()
    5462  *
    5463  * @param array $posts Array of Post objects
    5464  * @param string $post_type The post type of the posts in $posts. Default is 'post'.
    5465  * @param bool $update_term_cache Whether to update the term cache. Default is true.
    5466  * @param bool $update_meta_cache Whether to update the meta cache. Default is true.
    5467  */
    5468 function update_post_caches(&$posts, $post_type = 'post', $update_term_cache = true, $update_meta_cache = true) {
     5479 * @param array  $posts             Array of Post objects
     5480 * @param string $post_type         Optional. Post type. Default 'post'.
     5481 * @param bool   $update_term_cache Optional. Whether to update the term cache. Default true.
     5482 * @param bool   $update_meta_cache Optional. Whether to update the meta cache. Default true.
     5483 */
     5484function update_post_caches( &$posts, $post_type = 'post', $update_term_cache = true, $update_meta_cache = true ) {
    54695485    // No point in doing all this work if we didn't match any posts.
    54705486    if ( !$posts )
    … …  
    55105526 *
    55115527 * @param array $post_ids List of post IDs.
    5512  * @return bool|array Returns false if there is nothing to update or an array of metadata.
    5513  */
    5514 function update_postmeta_cache($post_ids) {
     5528 * @return bool|array Returns false if there is nothing to update or an array
     5529 *                    of metadata.
     5530 */
     5531function update_postmeta_cache( $post_ids ) {
    55155532    return update_meta_cache('post', $post_ids);
    55165533}
    … …  
    55225539 * object cache associated with the attachment ID.
    55235540 *
    5524  * This function will not run if $_wp_suspend_cache_invalidation is not empty. See
    5525  * wp_suspend_cache_invalidation().
     5541 * This function will not run if $_wp_suspend_cache_invalidation is not empty.
    55265542 *
    55275543 * @since 3.0.0
    55285544 *
    5529  * @param int $id The attachment ID in the cache to clean
    5530  * @param bool $clean_terms optional. Whether to clean terms cache
    5531  */
    5532 function clean_attachment_cache($id, $clean_terms = false) {
     5545 * @see wp_suspend_cache_invalidation()
     5546 *
     5547 * @param int  $id          The attachment ID in the cache to clean.
     5548 * @param bool $clean_terms Optional. Whether to clean terms cache. Default false.
     5549 */
     5550function clean_attachment_cache( $id, $clean_terms = false ) {
    55335551    global $_wp_suspend_cache_invalidation;
    55345552
    … …  
    55635581 * @since 2.3.0
    55645582 * @access private
    5565  * @uses $wpdb
    5566  * @uses wp_clear_scheduled_hook() with 'publish_future_post' and post ID.
    5567  *
    5568  * @param string $new_status New post status
    5569  * @param string $old_status Previous post status
    5570  * @param object $post Object type containing the post information
    5571  */
    5572 function _transition_post_status($new_status, $old_status, $post) {
     5583 *
     5584 * @see wp_clear_scheduled_hook()
     5585 * @global wpdb $wpdb WordPress database access abstraction object.
     5586 *
     5587 * @param string  $new_status New post status.
     5588 * @param string  $old_status Previous post status.
     5589 * @param WP_Post $post       Post object.
     5590 */
     5591function _transition_post_status( $new_status, $old_status, $post ) {
    55735592    global $wpdb;
    55745593
    … …  
    56145633 * @access private
    56155634 *
    5616  * @param int $deprecated Not used. Can be set to null. Never implemented.
    5617  *   Not marked as deprecated with _deprecated_argument() as it conflicts with
    5618  *   wp_transition_post_status() and the default filter for _future_post_hook().
    5619  * @param object $post Object type containing the post information
     5635 * @param int     $deprecated Not used. Can be set to null. Never implemented. Not marked
     5636 *                            as deprecated with _deprecated_argument() as it conflicts with
     5637 *                            wp_transition_post_status() and the default filter for
     5638 *                            {@see _future_post_hook()}.
     5639 * @param WP_Post $post       Post object.
    56205640 */
    56215641function _future_post_hook( $deprecated, $post ) {
    … …  
    56275647 * Hook to schedule pings and enclosures when a post is published.
    56285648 *
     5649 * Uses XMLRPC_REQUEST and WP_IMPORTING constants.
     5650 *
    56295651 * @since 2.3.0
    56305652 * @access private
    5631  * @uses XMLRPC_REQUEST and WP_IMPORTING constants.
    5632  *
    5633  * @param int $post_id The ID in the database table of the post being published
    5634  */
    5635 function _publish_post_hook($post_id) {
     5653 *
     5654 * @param int $post_id The ID in the database table of the post being published.
     5655 */
     5656function _publish_post_hook( $post_id ) {
    56365657    if ( defined( 'XMLRPC_REQUEST' ) ) {
    56375658        /**
    … …  
    56565677
    56575678/**
    5658  * Returns the post's parent's post_ID
     5679 * Return the post's parent's post_ID
    56595680 *
    56605681 * @since 3.1.0
    … …  
    56625683 * @param int $post_id
    56635684 *
    5664  * @return int|bool false on error
     5685 * @return int|bool Post parent ID, otherwise false.
    56655686 */
    56665687function wp_get_post_parent_id( $post_ID ) {
    … …  
    56725693
    56735694/**
    5674  * Checks the given subset of the post hierarchy for hierarchy loops.
    5675  * Prevents loops from forming and breaks those that it finds.
    5676  *
    5677  * Attached to the wp_insert_post_parent filter.
     5695 * Check the given subset of the post hierarchy for hierarchy loops.
     5696 *
     5697 * Prevents loops from forming and breaks those that it finds. Attached
     5698 * to the 'wp_insert_post_parent' filter.
    56785699 *
    56795700 * @since 3.1.0
    5680  * @uses wp_find_hierarchy_loop()
     5701 *
     5702 * @see wp_find_hierarchy_loop()
    56815703 *
    56825704 * @param int $post_parent ID of the parent for the post we're checking.
    5683  * @param int $post_ID ID of the post we're checking.
    5684  *
    5685  * @return int The new post_parent for the post.
     5705 * @param int $post_ID     ID of the post we're checking.
     5706 * @return int The new post_parent for the post, 0 otherwise.
    56865707 */
    56875708function wp_check_post_hierarchy_for_loops( $post_parent, $post_ID ) {
    … …  
    57155736
    57165737/**
    5717  * Sets a post thumbnail.
     5738 * Set a post thumbnail.
    57185739 *
    57195740 * @since 3.1.0
    57205741 *
    5721  * @param int|WP_Post $post Post ID or post object where thumbnail should be attached.
    5722  * @param int $thumbnail_id Thumbnail to attach.
     5742 * @param int|WP_Post $post         Post ID or post object where thumbnail should be attached.
     5743 * @param int         $thumbnail_id Thumbnail to attach.
    57235744 * @return bool True on success, false on failure.
    57245745 */
    … …  
    57365757
    57375758/**
    5738  * Removes a post thumbnail.
     5759 * Remove a post thumbnail.
    57395760 *
    57405761 * @since 3.3.0
    … …  
    57515772
    57525773/**
    5753  * Deletes auto-drafts for new posts that are > 7 days old
     5774 * Delete auto-drafts for new posts that are > 7 days old.
    57545775 *
    57555776 * @since 3.4.0
     5777 *
     5778 * @global wpdb $wpdb WordPress database access abstraction object.
    57565779 */
    57575780function wp_delete_auto_drafts() {
    57585781    global $wpdb;
    57595782
    5760     // Cleanup old auto-drafts more than 7 days old
     5783    // Cleanup old auto-drafts more than 7 days old.
    57615784    $old_posts = $wpdb->get_col( "SELECT ID FROM $wpdb->posts WHERE post_status = 'auto-draft' AND DATE_SUB( NOW(), INTERVAL 7 DAY ) > post_date" );
    5762     foreach ( (array) $old_posts as $delete )
    5763         wp_delete_post( $delete, true ); // Force delete
     5785    foreach ( (array) $old_posts as $delete ) {
     5786        // Force delete.
     5787        wp_delete_post( $delete, true );
     5788    }
    57645789}
    57655790
    … …  
    57675792 * Update the custom taxonomies' term counts when a post's status is changed. For example, default posts term counts (for custom taxonomies) don't include private / draft posts.
    57685793 *
     5794 * @since 3.3.0
    57695795 * @access private
    5770  * @param string $new_status
    5771  * @param string $old_status
    5772  * @param object $post
    5773  * @since 3.3.0
     5796 *
     5797 * @param string  $new_status New post status.
     5798 * @param string  $old_status Old post status.
     5799 * @param WP_Post $post       Post object.
    57745800 */
    57755801function _update_term_count_on_transition_post_status( $new_status, $old_status, $post ) {
    … …  
    57885814 * @access private
    57895815 *
    5790  * @param array $post_ids ID list
    5791  * @param bool $update_term_cache Whether to update the term cache. Default is true.
    5792  * @param bool $update_meta_cache Whether to update the meta cache. Default is true.
     5816 * @param array $post_ids          ID list
     5817 * @param bool  $update_term_cache Optional. Whether to update the term cache. Default true.
     5818 * @param bool  $update_meta_cache Optional. Whether to update the meta cache. Default true.
    57935819 */
    57945820function _prime_post_caches( $ids, $update_term_cache = true, $update_meta_cache = true ) {
    … …  
    58025828    }
    58035829}
    5804 
    5805 
Note: See TracChangeset for help on using the changeset viewer.