WordPress.org
Get WordPress

Make WordPress Core


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

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

First-run. See #25412.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r28976 r29090  
    181181 * @since 2.0.0
    182182 *
    183  * @param int $attachment_id Attachment ID.
    184  * @param bool $unfiltered Whether to apply filters.
     183 * @param int  $attachment_id Attachment ID.
     184 * @param bool $unfiltered    Optional. Whether to apply filters. Default false.
    185185 * @return string|bool The file path to where the attached file should be, false otherwise.
    186186 */
    187187function get_attached_file( $attachment_id, $unfiltered = false ) {
    188188    $file = get_post_meta( $attachment_id, '_wp_attached_file', true );
    189     // If the file is relative, prepend upload dir
     189    // If the file is relative, prepend upload dir.
    190190    if ( $file && 0 !== strpos($file, '/') && !preg_match('|^.:\\\|', $file) && ( ($uploads = wp_upload_dir()) && false === $uploads['error'] ) )
    191191        $file = $uploads['basedir'] . "/$file";
    … …  
    212212 * @since 2.1.0
    213213 *
    214  * @param int $attachment_id Attachment ID
    215  * @param string $file File path for the attachment
     214 * @param int    $attachment_id Attachment ID.
     215 * @param string $file          File path for the attachment.
    216216 * @return bool True on success, false on failure.
    217217 */
    … …  
    243243 * @since 2.9.0
    244244 *
    245  * @param string $path Full path to the file
    246  * @return string relative path on success, unchanged path on failure.
     245 * @param string $path Full path to the file.
     246 * @return string Relative path on success, unchanged path on failure.
    247247 */
    248248function _wp_relative_upload_path( $path ) {
    … …  
    305305 * argument will accept any post status within the write administration panels.
    306306 *
     307 * @internal Claims made in the long description might be inaccurate.
     308 * @since 2.0.0
     309 *
    307310 * @see get_posts() Has additional arguments that can be replaced.
    308  * @internal Claims made in the long description might be inaccurate.
    309  *
    310  * @since 2.0.0
    311  *
    312  * @param mixed $args Optional. User defined arguments for replacing the defaults.
    313  * @param string $output Optional. Constant for return type, either OBJECT (default), ARRAY_A, ARRAY_N.
     311 *
     312 * @param mixed  $args   Optional. User defined arguments for replacing the defaults. Default empty.
     313 * @param string $output Optional. Constant for return type. Accepts OBJECT, ARRAY_A, ARRAY_N.
     314 *                       Default OBJECt.
    314315 * @return array Array of children, where the type of each element is determined by $output parameter.
    315316 *               Empty array on failure.
    316317 */
    317 function get_children($args = '', $output = OBJECT) {
     318function get_children( $args = '', $output = OBJECT ) {
    318319    $kids = array();
    319320    if ( empty( $args ) ) {
    … …  
    380381 * @return array Post before ('main'), after ('extended'), and custom readmore ('more_text').
    381382 */
    382 function get_extended($post) {
    383     //Match the new style more links
     383function get_extended( $post ) {
     384    //Match the new style more links.
    384385    if ( preg_match('/<!--more(.*?)?-->/', $post, $matches) ) {
    385386        list($main, $extended) = explode($matches[0], $post, 2);
    … …  
    406407 *
    407408 * @since 1.5.1
    408  * @link http://codex.wordpress.org/Function_Reference/get_post
    409  *
    410  * @param int|WP_Post $post Optional. Post ID or post object.
    411  * @param string $output Optional, default is Object. Either OBJECT, ARRAY_A, or ARRAY_N.
    412  * @param string $filter Optional, default is raw.
    413  * @return WP_Post|null WP_Post on success or null on failure
     409 *
     410 * @see http://codex.wordpress.org/Function_Reference/get_post
     411 *
     412 * @param int|WP_Post $post   Optional. Post ID or post object. Defaults to global $post.
     413 * @param string      $output Optional, default is Object. Accepts OBJECT, ARRAY_A, or ARRAY_N.
     414 *                            Default OBJECT.
     415 * @param string      $filter Optional. Type of filter to apply. Accepts 'raw', 'edit', 'db',
     416 *                            or 'display'. Default 'raw'.
     417 * @return WP_Post|null WP_Post on success or null on failure.
    414418 */
    415419function get_post( $post = null, $output = OBJECT, $filter = 'raw' ) {
    … …  
    628632    public $filter;
    629633
     634    /**
     635     * Retrieve WP_Post instance.
     636     *
     637     * @static
     638     * @access public
     639     *
     640     * @param int $post_id Post ID.
     641     * @return WP_Post|bool Post object, false otherwise.
     642     */
    630643    public static function get_instance( $post_id ) {
    631644        global $wpdb;
    … …  
    652665    }
    653666
     667    /**
     668     * Constructor.
     669     *
     670     * @param WP_Post $post Post object.
     671     */
    654672    public function __construct( $post ) {
    655673        foreach ( get_object_vars( $post ) as $key => $value )
    … …  
    657675    }
    658676
     677    /**
     678     * Isset-er.
     679     *
     680     * @param string $key Property to check if set.
     681     * @return bool
     682     */
    659683    public function __isset( $key ) {
    660684        if ( 'ancestors' == $key )
    … …  
    673697    }
    674698
     699    /**
     700     * Getter.
     701     *
     702     * @param string $key Key to get.
     703     * @return array|mixed
     704     */
    675705    public function __get( $key ) {
    676706        if ( 'page_template' == $key && $this->__isset( $key ) ) {
    … …  
    698728        }
    699729
    700         // Rest of the values need filtering
    701 
     730        // Rest of the values need filtering.
    702731        if ( 'ancestors' == $key )
    703732            $value = get_post_ancestors( $this );
    … …  
    711740    }
    712741
     742    /**
     743     * {@Missing Summary}
     744     *
     745     * @param string $filter Filter.
     746     * @return $this|array|bool|object|WP_Post
     747     */
    713748    public function filter( $filter ) {
    714749        if ( $this->filter == $filter )
    … …  
    721756    }
    722757
     758    /**
     759     * Convert object to array.
     760     *
     761     * @return array Object as array.
     762     */
    723763    public function to_array() {
    724764        $post = get_object_vars( $this );
    … …  
    772812 *
    773813 * @since 2.3.0
    774  * @uses sanitize_post_field() See for possible $context values.
    775  *
    776  * @param string $field Post field name.
    777  * @param int|WP_Post $post Post ID or post object.
    778  * @param string $context Optional. How to filter the field. Default is 'display'.
     814 *
     815 * @see sanitize_post_field()
     816 *
     817 * @param string      $field   Post field name.
     818 * @param int|WP_Post $post    Post ID or post object.
     819 * @param string      $context Optional. How to filter the field. Accepts 'raw', 'edit', 'db',
     820 *                             or 'display'. Default 'display'.
    779821 * @return string The value of the post field on success, empty string on failure.
    780822 */
    … …  
    799841 * @since 2.0.0
    800842 *
    801  * @param int|WP_Post $ID Optional. Post ID or post object.
     843 * @param int|WP_Post $ID Optional. Post ID or post object. Default empty.
    802844 * @return string|bool The mime type on success, false on failure.
    803845 */
    804 function get_post_mime_type($ID = '') {
     846function get_post_mime_type( $ID = '' ) {
    805847    $post = get_post($ID);
    806848
    … …  
    819861 * @since 2.0.0
    820862 *
    821  * @param int|WP_Post $ID Optional. Post ID or post object.
     863 * @param int|WP_Post $ID Optional. Post ID or post object. Default empty.
    822864 * @return string|bool Post status on success, false on failure.
    823865 */
    824 function get_post_status($ID = '') {
     866function get_post_status( $ID = '' ) {
    825867    $post = get_post($ID);
    826868
    … …  
    863905function get_post_statuses() {
    864906    $status = array(
    865         'draft'         => __('Draft'),
    866         'pending'       => __('Pending Review'),
    867         'private'       => __('Private'),
    868         'publish'       => __('Published')
     907        'draft'   => __( 'Draft' ),
     908        'pending' => __( 'Pending Review' ),
     909        'private' => __( 'Private' ),
     910        'publish' => __( 'Published' )
    869911    );
    870912
    … …  
    884926function get_page_statuses() {
    885927    $status = array(
    886         'draft'         => __('Draft'),
    887         'private'       => __('Private'),
    888         'publish'       => __('Published')
     928        'draft'   => __( 'Draft' ),
     929        'private' => __( 'Private' ),
     930        'publish' => __( 'Published' )
    889931    );
    890932
    … …  
    899941 * parameter), along with a string for the post status name.
    900942 *
    901  *
    902  * Optional $args contents:
    903  *
    904  * label - A descriptive name for the post status marked for translation. Defaults to $post_status.
    905  * public - Whether posts of this status should be shown in the front end of the site. Defaults to true.
    906  * exclude_from_search - Whether to exclude posts with this post status from search results. Defaults to false.
    907  * show_in_admin_all_list - Whether to include posts in the edit listing for their post type
    908  * show_in_admin_status_list - Show in the list of statuses with post counts at the top of the edit
    909  *                             listings, e.g. All (12) | Published (9) | My Custom Status (2) ...
    910  *
    911943 * Arguments prefixed with an _underscore shouldn't be used by plugins and themes.
    912944 *
    … …  
    915947 *
    916948 * @param string $post_status Name of the post status.
    917  * @param array|string $args See above description.
    918  */
    919 function register_post_status($post_status, $args = array()) {
     949 * @param array|string $args {
     950 *     Optional. Array or string of post status arguments.
     951 *
     952 *     @type bool|string $label                     A descriptive name for the post status marked
     953 *                                                  for translation. Defaults to value of $post_status.
     954 *     @type bool|array  $label_count               Descriptive text to use for nooped plurals.
     955 *                                                  Default array of $label, twice
     956 *     @type bool        $exclude_from_search       Whether to exclude posts with this post status
     957 *                                                  from search results. Default is value of $internal.
     958 *     @type bool        $_builtin                  Whether the status is built-in. Core-use only.
     959 *                                                  Default false.
     960 *     @type bool        $public                    Whether posts of this status should be shown
     961 *                                                  in the front end of the site. Default true.
     962 *     @type bool        $internal                  Whether the status is for internal use only.
     963 *                                                  Default false.
     964 *     @type bool        $protected                 Whether posts with this status should be protected.
     965 *                                                  Default false.
     966 *     @type bool        $private                   Whether posts with this status should be private.
     967 *                                                  Default false.
     968 *     @type bool        $publicly_queryable        Whether posts with this status should be publicly-
     969 *                                                  queryable. Default is value of $public.
     970 *     @type bool        $show_in_admin_all_list    Whether to include posts in the edit listing for
     971 *                                                  their post type. Default is value of $internal.
     972 *     @type bool        $show_in_admin_status_list Show in the list of statuses with post counts at
     973 *                                                  the top of the edit listings,
     974 *                                                  e.g. All (12) | Published (9) | My Custom Status (2)
     975 *                                                  Default is value of $internal.
     976 * }
     977 */
     978function register_post_status( $post_status, $args = array() ) {
    920979    global $wp_post_statuses;
    921980
    … …  
    9431002    $args->name = $post_status;
    9441003
     1004    // Set various defaults.
    9451005    if ( null === $args->public && null === $args->internal && null === $args->protected && null === $args->private )
    9461006        $args->internal = true;
    … …  
    9821042
    9831043/**
    984  * Retrieve a post status object by name
     1044 * Retrieve a post status object by name.
    9851045 *
    9861046 * @since 3.0.0
    987  * @uses $wp_post_statuses
    988  * @see register_post_status
    989  * @see get_post_statuses
    990  *
    991  * @param string $post_status The name of a registered post status
    992  * @return object A post status object
     1047 *
     1048 * @global array $wp_post_statuses List of post statuses.
     1049 *
     1050 * @see register_post_status()
     1051 *
     1052 * @param string $post_status The name of a registered post status.
     1053 * @return object A post status object.
    9931054 */
    9941055function get_post_status_object( $post_status ) {
    … …  
    10051066 *
    10061067 * @since 3.0.0
    1007  * @uses $wp_post_statuses
    1008  * @see register_post_status
    1009  * @see get_post_status_object
    1010  *
    1011  * @param array|string $args An array of key => value arguments to match against the post status objects.
    1012  * @param string $output The type of output to return, either post status 'names' or 'objects'. 'names' is the default.
    1013  * @param string $operator The logical operation to perform. 'or' means only one element
    1014  *  from the array needs to match; 'and' means all elements must match. The default is 'and'.
    1015  * @return array A list of post status names or objects
     1068 *
     1069 * @global array $wp_post_statuses List of post statuses.
     1070 *
     1071 * @see register_post_status()
     1072 *
     1073 * @param array|string $args     Optional. Array or string of post status arguments. Default array.
     1074 * @param string       $output   Optional. The type of output to return. Accepts post status 'names'
     1075 *                               or 'objects'. Default 'names'.
     1076 * @param string       $operator Optional. The logical operation to perform. 'or' means only one element
     1077 *                               from the array needs to match; 'and' means all elements must match.
     1078 *                               Default 'and'.
     1079 * @return array A list of post status names or objects.
    10161080 */
    10171081function get_post_stati( $args = array(), $output = 'names', $operator = 'and' ) {
    … …  
    10291093 *
    10301094 * @since 3.0.0
    1031  * @see get_post_type_object
     1095 *
     1096 * @see get_post_type_object()
    10321097 *
    10331098 * @param string $post_type Post type name
    … …  
    10431108
    10441109/**
    1045  * Checks if a post type is registered.
     1110 * Check if a post type is registered.
    10461111 *
    10471112 * @since 3.0.0
    1048  * @uses get_post_type_object()
    1049  *
    1050  * @param string $post_type Post type name
     1113 *
     1114 * @see get_post_type_object()
     1115 *
     1116 * @param string $post_type Post type name.
    10511117 * @return bool Whether post type is registered.
    10521118 */
    … …  
    10601126 * @since 2.1.0
    10611127 *
    1062  * @param int|WP_Post $post Optional. Post ID or post object.
     1128 * @param int|WP_Post $post Optional. Post ID or post object. Default is global $post.
    10631129 * @return string|bool Post type on success, false on failure.
    10641130 */
    … …  
    10711137
    10721138/**
    1073  * Retrieve a post type object by name
     1139 * Retrieve a post type object by name.
    10741140 *
    10751141 * @since 3.0.0
    1076  * @uses $wp_post_types
    1077  * @see register_post_type
    1078  * @see get_post_types
    1079  *
    1080  * @param string $post_type The name of a registered post type
    1081  * @return object A post type object
     1142 *
     1143 * @global array $wp_post_types List of post types.
     1144 *
     1145 * @see register_post_type()
     1146 *
     1147 * @param string $post_type The name of a registered post type.
     1148 * @return object A post type object.
    10821149 */
    10831150function get_post_type_object( $post_type ) {
    … …  
    10941161 *
    10951162 * @since 2.9.0
    1096  * @uses $wp_post_types
    1097  * @see register_post_type
    1098  *
    1099  * @param array|string $args An array of key => value arguments to match against the post type objects.
    1100  * @param string $output The type of output to return, either post type 'names' or 'objects'. 'names' is the default.
    1101  * @param string $operator The logical operation to perform. 'or' means only one element
    1102  *  from the array needs to match; 'and' means all elements must match. The default is 'and'.
    1103  * @return array A list of post type names or objects
     1163 *
     1164 * @global array $wp_post_types List of post types.
     1165 *
     1166 * @see register_post_type()
     1167 *
     1168 * @param array|string $args     Optional. An array of key => value arguments to match against
     1169 *                               the post type objects. Default empty array.
     1170 * @param string       $output   Optional. The type of output to return. Accepts post type 'names'
     1171 *                               or 'objects'. Default 'names'.
     1172 * @param string       $operator Optaionl. The logical operation to perform. 'or' means only one
     1173 *                               element from the array needs to match; 'and' means all elements
     1174 *                               must match. Default 'and'.
     1175 * @return array A list of post type names or objects.
    11041176 */
    11051177function get_post_types( $args = array(), $output = 'names', $operator = 'and' ) {
Note: See TracChangeset for help on using the changeset viewer.