WordPress.org

Make WordPress Core

Changeset 32619


Ignore:
Timestamp:
05/27/2015 05:04:45 PM (6 years ago)
Author:
wonderboymusic
Message:

Add missing doc blocks to post.php.
Clarify some existing values for @param and @return.
Some functions do not need to set a variable before immediately returning it.

See #32444.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/post.php

    r32545 r32619  
    182182 * @param int  $attachment_id Attachment ID.
    183183 * @param bool $unfiltered    Optional. Whether to apply filters. Default false.
    184  * @return string|bool The file path to where the attached file should be, false otherwise.
     184 * @return string|false The file path to where the attached file should be, false otherwise.
    185185 */
    186186function get_attached_file( $attachment_id, $unfiltered = false ) {
     
    308308 * @see get_posts()
    309309 * @todo Check validity of description.
     310 *
     311 * @global WP_Post $post
    310312 *
    311313 * @param mixed  $args   Optional. User defined arguments for replacing the defaults. Default empty.
     
    411413 * @since 1.5.1
    412414 *
    413  * @param int|WP_Post $post   Optional. Post ID or post object. Defaults to global $post.
    414  * @param string      $output Optional, default is Object. Accepts OBJECT, ARRAY_A, or ARRAY_N.
    415  *                            Default OBJECT.
    416  * @param string      $filter Optional. Type of filter to apply. Accepts 'raw', 'edit', 'db',
    417  *                            or 'display'. Default 'raw'.
     415 * @global WP_Post $post
     416 *
     417 * @param int|WP_Post|null $post   Optional. Post ID or post object. Defaults to global $post.
     418 * @param string           $output Optional, default is Object. Accepts OBJECT, ARRAY_A, or ARRAY_N.
     419 *                                 Default OBJECT.
     420 * @param string           $filter Optional. Type of filter to apply. Accepts 'raw', 'edit', 'db',
     421 *                                 or 'display'. Default 'raw'.
    418422 * @return WP_Post|array|null Type corresponding to $output on success or null on failure.
    419423 *                            When $output is OBJECT, a `WP_Post` instance is returned.
     
    645649     * @access public
    646650     *
     651     * @global wpdb $wpdb
     652     *
    647653     * @param int $post_id Post ID.
    648      * @return WP_Post|bool Post object, false otherwise.
     654     * @return WP_Post|false Post object, false otherwise.
    649655     */
    650656    public static function get_instance( $post_id ) {
     
    708714     *
    709715     * @param string $key Key to get.
    710      * @return array|mixed
     716     * @return mixed
    711717     */
    712718    public function __get( $key ) {
     
    751757     *
    752758     * @param string $filter Filter.
    753      * @return $this|array|bool|object|WP_Post
     759     * @return self|array|bool|object|WP_Post
    754760     */
    755761    public function filter( $filter ) {
     
    951957 *
    952958 * @since 3.0.0
    953  * @uses $wp_post_statuses Inserts new post status object into the list
     959 * @global array $wp_post_statuses Inserts new post status object into the list
    954960 *
    955961 * @param string $post_status Name of the post status.
     
    982988 *                                                  Default is value of $internal.
    983989 * }
     990 * @return object
    984991 */
    985992function register_post_status( $post_status, $args = array() ) {
     
    10581065 *
    10591066 * @param string $post_status The name of a registered post status.
    1060  * @return object A post status object.
     1067 * @return object|null A post status object.
    10611068 */
    10621069function get_post_status_object( $post_status ) {
     
    11331140 * @since 2.1.0
    11341141 *
    1135  * @param int|WP_Post $post Optional. Post ID or post object. Default is global $post.
    1136  * @return string|false Post type on success, false on failure.
     1142 * @param int|WP_Post|null $post Optional. Post ID or post object. Default is global $post.
     1143 * @return string|false          Post type on success, false on failure.
    11371144 */
    11381145function get_post_type( $post = null ) {
     
    11531160 *
    11541161 * @param string $post_type The name of a registered post type.
    1155  * @return object A post type object.
     1162 * @return object|null A post type object.
    11561163 */
    11571164function get_post_type_object( $post_type ) {
     
    15821589 * @access private
    15831590 *
    1584  * @param null|array $capabilities Post type meta capabilities.
     1591 * @staticvar array $meta_caps
     1592 *
     1593 * @param array|void $capabilities Post type meta capabilities.
    15851594 */
    15861595function _post_type_meta_capabilities( $capabilities = null ) {
     
    16961705    }
    16971706    $labels = array_merge( $defaults, $object->labels );
    1698     return (object)$labels;
     1707    return (object) $labels;
    16991708}
    17001709
     
    17291738 * @since 3.0.0
    17301739 *
     1740 * @global array $_wp_post_type_features
     1741 *
    17311742 * @param string       $post_type The post type for which to add the feature.
    17321743 * @param string|array $feature   The feature being added, accepts an array of
     
    17501761 * @since 3.0.0
    17511762 *
     1763 * @global array $_wp_post_type_features
     1764 *
    17521765 * @param string $post_type The post type for which to remove the feature.
    17531766 * @param string $feature   The feature being removed.
     
    17641777 * @since 3.4.0
    17651778 *
     1779 * @global array $_wp_post_type_features
     1780 *
    17661781 * @param string $post_type The post type.
    17671782 * @return array Post type supports list.
     
    17811796 * @since 3.0.0
    17821797 *
     1798 * @global array $_wp_post_type_features
     1799 *
    17831800 * @param string $post_type The post type being checked.
    1784  * @param string $feature the feature being checked.
     1801 * @param string $feature   The feature being checked.
    17851802 * @return bool Whether the post type supports the given feature.
    17861803 */
     
    18031820 * @param string $post_type Optional. Post type. Accepts 'post' or 'page' to
    18041821 *                          name a few. Default 'post'.
    1805  * @return int Amount of rows changed. Should be 1 for success and 0 for failure.
     1822 * @return int|false Amount of rows changed. Should be 1 for success and 0 for failure.
    18061823 */
    18071824function set_post_type( $post_id = 0, $post_type = 'post' ) {
     
    18931910 * @param bool   $unique     Optional. Whether the same key should not be added.
    18941911 *                           Default false.
    1895  * @return int|bool Meta ID on success, false on failure.
     1912 * @return int|false Meta ID on success, false on failure.
    18961913 */
    18971914function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
     
    20072024 *
    20082025 * @param int $post_id Optional. Post ID. Default is ID of the global $post.
    2009  * @return array|null Either array of the keys, or null if keys could not be
    2010  *                    retrieved.
     2026 * @return array|void Array of the keys, if retrieved.
    20112027 */
    20122028function get_post_custom_keys( $post_id = 0 ) {
     
    20302046 * @param string $key     Optional. Meta field key. Default empty.
    20312047 * @param int    $post_id Optional. Post ID. Default is ID of the global $post.
    2032  * @return array Meta field values.
     2048 * @return array|null Meta field values.
    20332049 */
    20342050function get_post_custom_values( $key = '', $post_id = 0 ) {
     
    23432359 * @since 2.5.0
    23442360 *
     2361 * @global wpdb $wpdb
     2362 *
    23452363 * @param string $type Optional. Post type to retrieve count. Default 'post'.
    23462364 * @param string $perm Optional. 'readable' or empty. Default empty.
     
    24052423 *
    24062424 * @since 2.5.0
     2425 *
     2426 * @global wpdb $wpdb
    24072427 *
    24082428 * @param string|array $mime_type Optional. Array or comma-separated list of
     
    25802600 * @param bool $force_delete Optional. Whether to bypass trash and force deletion.
    25812601 *                           Default false.
    2582  * @return array|bool|WP_Post False on failure.
     2602 * @return array|false|WP_Post False on failure.
    25832603 */
    25842604function wp_delete_post( $postid = 0, $force_delete = false ) {
     
    27232743 * @param int $post_id Optional. Post ID. Default is ID of the global $post
    27242744 *                     if EMPTY_TRASH_DAYS equals true.
    2725  * @return bool|array Post data array, otherwise false.
     2745 * @return false|array|WP_Post|null Post data array, otherwise false.
    27262746 */
    27272747function wp_trash_post( $post_id = 0 ) {
     
    27702790 *
    27712791 * @param int $post_id Optional. Post ID. Default is ID of the global $post.
    2772  * @return WP_Post|bool WP_Post object. False on failure.
     2792 * @return WP_Post|false WP_Post object. False on failure.
    27732793 */
    27742794function wp_untrash_post( $post_id = 0 ) {
     
    28182838 * @global wpdb $wpdb WordPress database abstraction object.
    28192839 *
    2820  * @param int|WP_Post $post Optional. Post ID or post object. Defaults to global $post.
    2821  * @return mixed False on failure.
     2840 * @param int|WP_Post|null $post Optional. Post ID or post object. Defaults to global $post.
     2841 * @return mixed|void False on failure.
    28222842 */
    28232843function wp_trash_post_comments( $post = null ) {
     
    28722892 * @since 2.9.0
    28732893 *
    2874  * @param int|WP_Post $post Optional. Post ID or post object. Defaults to global $post.
    2875  * @return null|bool Null on failure.
     2894 * @global wpdb $wpdb
     2895 *
     2896 * @param int|WP_Post|null $post Optional. Post ID or post object. Defaults to global $post.
     2897 * @return true|void
    28762898 */
    28772899function wp_untrash_post_comments( $post = null ) {
     
    30033025 * @param array  $args       Optional. Arguments to retrieve posts. Default empty array.
    30043026 * @param string $output     Optional. Type of output. Accepts ARRAY_A or ''. Default ARRAY_A.
    3005  * @return array|bool Associative array if $output equals ARRAY_A, array or false if no results.
     3027 * @return array|false Associative array if $output equals ARRAY_A, array or false if no results.
    30063028 */
    30073029function wp_get_recent_posts( $args = array(), $output = ARRAY_A ) {
     
    36623684 *
    36633685 * @param int|WP_Post $post_id Post ID or post object.
    3664  * @return null Nothing is returned. Which can mean that no action is required
    3665  *              or post was published.
    36663686 */
    36673687function check_and_publish_future_post( $post_id ) {
    3668 
    36693688    $post = get_post($post_id);
    36703689
     
    36843703    }
    36853704
    3686     return wp_publish_post($post_id);
     3705    // wp_publish_post(_ returns no meaninful value
     3706    wp_publish_post( $post_id );
    36873707}
    36883708
     
    36923712 * @since 2.8.0
    36933713 *
    3694  * @global wpdb $wpdb WordPress database abstraction object.
     3714 * @global wpdb       $wpdb WordPress database abstraction object.
    36953715 * @global WP_Rewrite $wp_rewrite
    36963716 *
     
    38403860 *                        Default 0.
    38413861 * @param string $tags    Optional. The tags to set for the post, separated by commas. Default empty.
    3842  * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise.
     3862 * @return array|false|WP_Error Will return false if $post_id is not an integer or is 0.
    38433863 */
    38443864function wp_add_post_tags( $post_id = 0, $tags = '' ) {
     
    38583878 * @param bool   $append  Optional. If true, don't delete existing tags, just add on. If false,
    38593879 *                        replace the tags with the new tags. Default false.
    3860  * @return mixed Array of affected term IDs. WP_Error or false on failure.
     3880 * @return array|false|WP_Error Array of affected term IDs. WP_Error or false on failure.
    38613881 */
    38623882function wp_set_post_tags( $post_id = 0, $tags = '', $append = false ) {
     
    38763896 * @param bool   $append   Optional. If true, don't delete existing tags, just add on. If false,
    38773897 *                         replace the tags with the new tags. Default false.
    3878  * @return mixed Array of affected term IDs. WP_Error or false on failure.
     3898 * @return array|false|WP_Error Array of affected term IDs. WP_Error or false on failure.
    38793899 */
    38803900function wp_set_post_terms( $post_id = 0, $tags = '', $taxonomy = 'post_tag', $append = false ) {
     
    39193939 * @param bool      $append         If true, don't delete existing categories, just add on.
    39203940 *                                  If false, replace the categories with the new categories.
    3921  * @return bool|mixed
     3941 * @return array|bool|WP_Error
    39223942 */
    39233943function wp_set_post_categories( $post_ID = 0, $post_categories = array(), $append = false ) {
     
    40184038 * @param int    $post_id Post ID.
    40194039 * @param string $uri     Ping URI.
    4020  * @return int How many rows were updated.
     4040 * @return int|false How many rows were updated.
    40214041 */
    40224042function add_ping( $post_id, $uri ) {
     
    40734093     * @param int   $post_id Post ID.
    40744094     */
    4075     $pung = apply_filters( 'get_enclosed', $pung, $post_id );
    4076     return $pung;
     4095    return apply_filters( 'get_enclosed', $pung, $post_id );
    40774096}
    40784097
     
    41004119     * @param array $pung Array of URLs already pinged for the given post.
    41014120     */
    4102     $pung = apply_filters( 'get_pung', $pung );
    4103     return $pung;
     4121    return apply_filters( 'get_pung', $pung );
    41044122}
    41054123
     
    41274145     * @param array $to_ping List of URLs yet to ping.
    41284146     */
    4129     $to_ping = apply_filters( 'get_to_ping', $to_ping );
    4130     return $to_ping;
     4147    return apply_filters( 'get_to_ping', $to_ping );
    41314148}
    41324149
     
    41974214 * @param string $filter Optional. How the return value should be filtered. Accepts 'raw',
    41984215 *                       'edit', 'db', 'display'. Default 'raw'.
    4199  * @return WP_Post|null WP_Post on success or null on failure.
     4216 * @return WP_Post|array|null WP_Post on success or null on failure.
    42004217 */
    42014218function get_page( $page, $output = OBJECT, $filter = 'raw') {
     
    42144231 *                                Default OBJECT.
    42154232 * @param string|array $post_type Optional. Post type or array of post types. Default 'page'.
    4216  * @return WP_Post|null WP_Post on success or null on failure.
     4233 * @return WP_Post|array|void WP_Post on success.
    42174234 */
    42184235function get_page_by_path( $page_path, $output = OBJECT, $post_type = 'page' ) {
     
    42684285    }
    42694286
    4270     if ( $foundid )
     4287    if ( $foundid ) {
    42714288        return get_post( $foundid, $output );
    4272 
    4273     return null;
     4289    }
    42744290}
    42754291
     
    42854301 *                                 Default OBJECT.
    42864302 * @param string|array $post_type  Optional. Post type or array of post types. Default 'page'.
    4287  * @return WP_Post|null WP_Post on success or null on failure
     4303 * @return WP_Post|array|void WP_Post on success or null on failure
    42884304 */
    42894305function get_page_by_title( $page_title, $output = OBJECT, $post_type = 'page' ) {
     
    43104326    $page = $wpdb->get_var( $sql );
    43114327
    4312     if ( $page )
     4328    if ( $page ) {
    43134329        return get_post( $page, $output );
    4314 
    4315     return null;
     4330    }
    43164331}
    43174332
     
    43704385function get_page_hierarchy( &$pages, $page_id = 0 ) {
    43714386    if ( empty( $pages ) ) {
    4372         $result = array();
    4373         return $result;
     4387        return array();
    43744388    }
    43754389
     
    44714485 *                                      Default 'publish'.
    44724486 * }
    4473  * @return array List of pages matching defaults or `$args`.
     4487 * @return array|false List of pages matching defaults or `$args`.
    44744488 */
    44754489function get_pages( $args = array() ) {
     
    47234737     * @param array $r     Array of get_pages() arguments.
    47244738     */
    4725     $pages = apply_filters( 'get_pages', $pages, $r );
    4726 
    4727     return $pages;
     4739    return apply_filters( 'get_pages', $pages, $r );
    47284740}
    47294741
     
    49114923 * @param int  $post_id    Attachment ID. Default 0.
    49124924 * @param bool $unfiltered Optional. If true, filters are not run. Default false.
    4913  * @return string|bool Attachment meta field. False on failure.
     4925 * @return mixed Attachment meta field. False on failure.
    49144926 */
    49154927function wp_get_attachment_metadata( $post_id = 0, $unfiltered = false ) {
     
    49684980 * @since 2.1.0
    49694981 *
     4982 * @global string $pagenow
     4983 *
    49704984 * @param int $post_id Optional. Attachment ID. Default 0.
    4971  * @return string|bool Attachment URL, otherwise false.
     4985 * @return string|false Attachment URL, otherwise false.
    49724986 */
    49734987function wp_get_attachment_url( $post_id = 0 ) {
     
    50325046 *
    50335047 * @param int $post_id Optional. Attachment ID. Default 0.
    5034  * @return mixed False on failure. Thumbnail file path on success.
     5048 * @return string|false False on failure. Thumbnail file path on success.
    50355049 */
    50365050function wp_get_attachment_thumb_file( $post_id = 0 ) {
     
    50635077 *
    50645078 * @param int $post_id Optional. Attachment ID. Default 0.
    5065  * @return string|bool False on failure. Thumbnail URL on success.
     5079 * @return string|false False on failure. Thumbnail URL on success.
    50665080 */
    50675081function wp_get_attachment_thumb_url( $post_id = 0 ) {
     
    51615175 *
    51625176 * @param string|int $mime MIME type or attachment ID.
    5163  * @return string|bool Icon, false otherwise.
     5177 * @return string|false Icon, false otherwise.
    51645178 */
    51655179function wp_mime_type_icon( $mime = 0 ) {
     
    52955309 * @param WP_Post $post        The Post Object
    52965310 * @param WP_Post $post_before The Previous Post Object
    5297  * @return int Same as $post_id
    52985311 */
    52995312function wp_check_for_changed_slugs( $post_id, $post, $post_before ) {
     
    53425355 *
    53435356 * @see get_private_posts_cap_sql()
     5357 *
     5358 * @global wpdb $wpdb
    53445359 *
    53455360 * @param array|string   $post_type   Single post type or an array of post types.
     
    54845499 * @access private
    54855500 *
     5501 * @global wpdb $wpdb
     5502 *
    54865503 * @param string $timezone The timezone for the timestamp. See {@see get_lastpostmodified()}
    54875504 *                         for information on accepted values.
    54885505 * @param string $field    Post field to check. Accepts 'date' or 'modified'.
    5489  * @return string The timestamp.
     5506 * @return string|false The timestamp.
    54905507 */
    54915508function _get_last_post_time( $timezone, $field ) {
     
    55535570 * @since 2.0.0
    55545571 *
     5572 * @global bool $_wp_suspend_cache_invalidation
    55555573 * @global wpdb $wpdb WordPress database abstraction object.
    55565574 *
     
    56565674 *
    56575675 * @param array $post_ids List of post IDs.
    5658  * @return bool|array Returns false if there is nothing to update or an array
    5659  *                    of metadata.
     5676 * @return array|false Returns false if there is nothing to update or an array
     5677 *                     of metadata.
    56605678 */
    56615679function update_postmeta_cache( $post_ids ) {
     
    56735691 * @since 3.0.0
    56745692 *
    5675  * @see wp_suspend_cache_invalidation()
     5693 * @global bool $_wp_suspend_cache_invalidation
    56765694 *
    56775695 * @param int  $id          The attachment ID in the cache to clean.
     
    58135831 * @param int $post_ID
    58145832 *
    5815  * @return int|bool Post parent ID, otherwise false.
     5833 * @return int|false Post parent ID, otherwise false.
    58165834 */
    58175835function wp_get_post_parent_id( $post_ID ) {
     
    58715889 * @param int|WP_Post $post         Post ID or post object where thumbnail should be attached.
    58725890 * @param int         $thumbnail_id Thumbnail to attach.
    5873  * @return bool True on success, false on failure.
     5891 * @return int|bool True on success, false on failure.
    58745892 */
    58755893function set_post_thumbnail( $post, $thumbnail_id ) {
     
    59475965 * @see update_post_caches()
    59485966 *
     5967 * @global wpdb $wpdb
     5968 *
    59495969 * @param array $ids               ID list
    59505970 * @param bool  $update_term_cache Optional. Whether to update the term cache. Default true.
Note: See TracChangeset for help on using the changeset viewer.