Make WordPress Core

Changeset 43582


Ignore:
Timestamp:
08/27/2018 02:27:22 PM (8 years ago)
Author:
johnbillion
Message:

Docs: Correct and improve various inline documentation.

See #42505

Location:
trunk/src
Files:
10 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/js/_enqueues/wp/media/editor.js

    r43347 r43582  
    610610                },
    611611                /**
    612                  * Set the featured image id, save the post thumbnail data and
    613                  * set the HTML in the post meta box to the new featured image.
     612                 * Sets the featured image ID property and sets the HTML in the post meta box to the new featured image.
    614613                 *
    615614                 * @param {number} id The post ID of the featured image, or -1 to unset it.
  • trunk/src/wp-admin/includes/post.php

    r43571 r43582  
    15201520         * @since 4.6.0 Added the `$thumbnail_id` parameter.
    15211521         *
    1522          * @param string $content      Admin post thumbnail HTML markup.
    1523          * @param int    $post_id      Post ID.
    1524          * @param int    $thumbnail_id Thumbnail ID.
     1522         * @param string   $content      Admin post thumbnail HTML markup.
     1523         * @param int      $post_id      Post ID.
     1524         * @param int|null $thumbnail_id Thumbnail attachment ID, or null if there isn't one.
    15251525         */
    15261526        return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID, $thumbnail_id );
  • trunk/src/wp-includes/class-wp-query.php

    r43571 r43582  
    16871687
    16881688        /**
    1689          * Retrieve the posts based on query variables.
     1689         * Retrieves an array of posts based on query variables.
    16901690         *
    16911691         * There are a few filters and actions that can be used to modify the post
    … …  
    16941694         * @since 1.5.0
    16951695         *
    1696          * @return array List of posts.
     1696         * @return WP_Post[]|int[] Array of post objects or post IDs.
    16971697         */
    16981698        public function get_posts() {
    … …  
    33583358         *
    33593359         * @param string|array $query URL query string or array of query arguments.
    3360          * @return array List of posts.
     3360         * @return WP_Post[]|int[] Array of post objects or post IDs.
    33613361         */
    33623362        public function query( $query ) {
  • trunk/src/wp-includes/class-wp-user.php

    r43571 r43582  
    8181         *
    8282         * @since 2.0.0
    83          * @var array
     83         * @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
     84         *             represent whether the user has that capability.
    8485         */
    8586        public $allcaps = array();
    … …  
    479480
    480481        /**
    481          * Retrieve all of the role capabilities and merge with individual capabilities.
    482          *
    483          * All of the capabilities of the roles the user belongs to are merged with
    484          * user's individual capabilities. This also means that the user can be denied
    485          * specific capabilities that their role might have, but the user isn't granted
    486          * permission to.
    487          *
    488          * @since 2.0.0
    489          *
    490          * @return array List of all capabilities for the user.
     482         * Retrieves all of the capabilities of the roles of the user, and merges them with individual user capabilities.
     483         *
     484         * All of the capabilities of the roles of the user are merged with the user's individual capabilities. This means
     485         * that the user can be denied specific capabilities that their role might have, but the user is specifically denied.
     486         *
     487         * @since 2.0.0
     488         *
     489         * @return bool[] Array of key/value pairs where keys represent a capability name and boolean values
     490         *                represent whether the user has that capability.
    491491         */
    492492        public function get_role_caps() {
    … …  
    752752                 *
    753753                 * @since 2.0.0
    754                  * @since 3.7.0 Added the user object.
     754                 * @since 3.7.0 Added the `$user` parameter.
    755755                 *
    756                  * @param bool[]   $allcaps An array of all the user's capabilities.
    757                  * @param string[] $caps    Actual capabilities for meta capability.
    758                  * @param array    $args    Optional parameters passed to has_cap(), typically object ID.
     756                 * @param bool[]   $allcaps Array of key/value pairs where keys represent a capability name and boolean values
     757                 *                          represent whether the user has that capability.
     758                 * @param string[] $caps    Required primitive capabilities for the requested capability.
     759                 * @param array    $args {
     760                 *     Arguments that accompany the requested capability check.
     761                 *
     762                 *     @type string    $0 Requested capability.
     763                 *     @type int       $1 Concerned user ID.
     764                 *     @type mixed  ...$2 Optional second and further parameters, typically object ID.
     765                 * }
    759766                 * @param WP_User  $user    The user object.
    760767                 */
  • trunk/src/wp-includes/general-template.php

    r43571 r43582  
    29052905
    29062906        /**
    2907          * Filters the site icon meta tags, so Plugins can add their own.
     2907         * Filters the site icon meta tags, so plugins can add their own.
    29082908         *
    29092909         * @since 4.3.0
    29102910         *
    2911          * @param array $meta_tags Site Icon meta elements.
     2911         * @param string[] $meta_tags Array of Site Icon meta tags.
    29122912         */
    29132913        $meta_tags = apply_filters( 'site_icon_meta_tags', $meta_tags );
  • trunk/src/wp-includes/media.php

    r43571 r43582  
    34153415         * @since 3.5.0
    34163416         *
    3417          * @param array   $response   Array of prepared attachment data.
    3418          * @param WP_Post $attachment Attachment object.
    3419          * @param array   $meta       Array of attachment meta data.
     3417         * @param array       $response   Array of prepared attachment data.
     3418         * @param WP_Post     $attachment Attachment object.
     3419         * @param array|false $meta       Array of attachment meta data, or false if there is none.
    34203420         */
    34213421        return apply_filters( 'wp_prepare_attachment_for_js', $response, $attachment, $meta );
  • trunk/src/wp-includes/meta.php

    r43571 r43582  
    151151 * @param mixed  $prev_value Optional. If specified, only update existing metadata entries with
    152152 *                           the specified value. Otherwise, update all entries.
    153  * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
     153 * @return int|bool The new meta field ID if a field with the given key didn't exist and was
     154 *                  therefore added, true on successful update, false on failure.
    154155 */
    155156function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_value = '' ) {
  • trunk/src/wp-includes/post.php

    r43571 r43582  
    18241824
    18251825/**
    1826  * Retrieve list of latest posts or posts matching criteria.
     1826 * Retrieves an array of the latest posts, or posts matching the given criteria.
    18271827 *
    18281828 * The defaults are as follows:
    … …  
    18451845 *     @type bool       $suppress_filters Whether to suppress filters. Default true.
    18461846 * }
    1847  * @return array List of posts.
     1847 * @return WP_Post[]|int[] Array of post objects or post IDs.
    18481848 */
    18491849function get_posts( $args = null ) {
    … …  
    18921892
    18931893/**
    1894  * Add meta data field to a post.
     1894 * Adds a meta field to the given post.
    18951895 *
    18961896 * Post meta data is called "Custom Fields" on the Administration Screen.
    … …  
    19191919
    19201920/**
    1921  * Remove metadata matching criteria from a post.
     1921 * Deletes a post meta field for the given post ID.
    19221922 *
    19231923 * You can match based on the key, or key and value. Removing based on key and
    19241924 * value, will keep from removing duplicate metadata with the same key. It also
    1925  * allows removing all metadata matching key, if needed.
     1925 * allows removing all metadata matching the key, if needed.
    19261926 *
    19271927 * @since 1.5.0
    … …  
    19471947
    19481948/**
    1949  * Retrieve post meta field for a post.
     1949 * Retrieves a post meta field for the given post ID.
    19501950 *
    19511951 * @since 1.5.0
    … …  
    19541954 * @param string $key     Optional. The meta key to retrieve. By default, returns
    19551955 *                        data for all keys. Default empty.
    1956  * @param bool   $single  Optional, default is false.
    1957  *                        If true, return only the first value of the specified meta_key.
    1958  *                        This parameter has no effect if meta_key is not specified.
    1959  * @return mixed Will be an array if $single is false. Will be value of meta data
     1956 * @param bool   $single  Optional. If true, returns only the first value for the specified meta key.
     1957 *                        This parameter has no effect if $key is not specified. Default false.
     1958 * @return mixed Will be an array if $single is false. Will be value of the meta
    19601959 *               field if $single is true.
    19611960 */
    … …  
    19651964
    19661965/**
    1967  * Update post meta field based on post ID.
     1966 * Updates a post meta field based on the given post ID.
    19681967 *
    19691968 * Use the $prev_value parameter to differentiate between meta fields with the
    19701969 * same key and post ID.
    19711970 *
    1972  * If the meta field for the post does not exist, it will be added.
     1971 * If the meta field for the post does not exist, it will be added and its ID returned.
    19731972 *
    19741973 * @since 1.5.0
    … …  
    19771976 * @param string $meta_key   Metadata key.
    19781977 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
    1979  * @param mixed  $prev_value Optional. Previous value to check before removing.
    1980  *                           Default empty.
    1981  * @return int|bool Meta ID if the key didn't exist, true on successful update,
    1982  *                  false on failure.
     1978 * @param mixed  $prev_value Optional. Previous value to check before updating.
     1979 * @return int|bool The new meta field ID if a field with the given key didn't exist and was
     1980 *                  therefore added, true on successful update, false on failure.
    19831981 */
    19841982function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
    … …  
    19961994
    19971995/**
    1998  * Delete everything from post meta matching meta key.
     1996 * Deletes everything from post meta matching the given meta key.
    19991997 *
    20001998 * @since 2.3.0
    … …  
    64916489
    64926490/**
    6493  * Return the post's parent post ID.
     6491 * Returns the ID of the post's parent.
    64946492 *
    64956493 * @since 3.1.0
    64966494 *
    64976495 * @param int|WP_Post $post Post ID or post object. Defaults to global $post.
    6498  * @return int|false Post parent ID, otherwise false.
     6496 * @return int|false Post parent ID (which can be 0 if there is no parent), or false if the post does not exist.
    64996497 */
    65006498function wp_get_post_parent_id( $post ) {
    … …  
    65606558
    65616559/**
    6562  * Set a post thumbnail.
     6560 * Sets the post thumbnail (featured image) for the given post.
    65636561 *
    65646562 * @since 3.1.0
    … …  
    65826580
    65836581/**
    6584  * Remove a post thumbnail.
     6582 * Removes the thumbnail (featured image) from the given post.
    65856583 *
    65866584 * @since 3.3.0
    65876585 *
    6588  * @param int|WP_Post $post Post ID or post object where thumbnail should be removed from.
     6586 * @param int|WP_Post $post Post ID or post object from which the thumbnail should be removed.
    65896587 * @return bool True on success, false on failure.
    65906588 */
  • trunk/src/wp-includes/rest-api/class-wp-rest-response.php

    r42343 r43582  
    194194
    195195        /**
    196          * Retrieves the handler that was responsible for generating the response.
     196         * Sets the handler that was responsible for generating the response.
    197197         *
    198198         * @since 4.4.0
  • trunk/src/wp-includes/rest-api/class-wp-rest-server.php

    r43571 r43582  
    905905                                 * @since 4.7.0
    906906                                 *
    907                                  * @param WP_HTTP_Response $response Result to send to the client. Usually a WP_REST_Response.
    908                                  * @param WP_REST_Server   $handler  ResponseHandler instance (usually WP_REST_Server).
    909                                  * @param WP_REST_Request  $request  Request used to generate the response.
     907                                 * @param WP_HTTP_Response|WP_Error $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
     908                                 * @param array                     $handler  Route handler used for the request.
     909                                 * @param WP_REST_Request           $request  Request used to generate the response.
    910910                                 */
    911911                                $response = apply_filters( 'rest_request_before_callbacks', $response, $handler, $request );
    … …  
    933933                                         * @since 4.5.0 Added `$route` and `$handler` parameters.
    934934                                         *
    935                                          * @param bool            $dispatch_result Dispatch result, will be used if not empty.
     935                                         * @param mixed           $dispatch_result Dispatch result, will be used if not empty.
    936936                                         * @param WP_REST_Request $request         Request used to generate the response.
    937937                                         * @param string          $route           Route matched for the request.
    … …  
    964964                                 * @since 4.7.0
    965965                                 *
    966                                  * @param WP_HTTP_Response $response Result to send to the client. Usually a WP_REST_Response.
    967                                  * @param WP_REST_Server   $handler  ResponseHandler instance (usually WP_REST_Server).
    968                                  * @param WP_REST_Request  $request  Request used to generate the response.
     966                                 * @param WP_HTTP_Response|WP_Error $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
     967                                 * @param array                     $handler  Route handler used for the request.
     968                                 * @param WP_REST_Request           $request  Request used to generate the response.
    969969                                 */
    970970                                $response = apply_filters( 'rest_request_after_callbacks', $response, $handler, $request );
Note: See TracChangeset for help on using the changeset viewer.