Make WordPress Core

Changeset 43582


Ignore:
Timestamp:
08/27/2018 02:27:22 PM (6 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.