Make WordPress Core


Ignore:
Timestamp:
06/02/2022 10:53:45 AM (22 months ago)
Author:
audrasjb
Message:

Docs: Use third-person singular verbs for method descriptions in wp-includes/post.php, as per docs standards.

Props whaze.
See #55646.

File:
1 edited

Legend:

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

    r53453 r53456  
    704704
    705705/**
    706  * Retrieve attached file path based on attachment ID.
     706 * Retrieves attached file path based on attachment ID.
    707707 *
    708708 * By default the path will go through the 'get_attached_file' filter, but
     
    748748
    749749/**
    750  * Update attachment file path based on attachment ID.
     750 * Updates attachment file path based on attachment ID.
    751751 *
    752752 * Used to update the file path of the attachment, which uses post meta name
     
    783783
    784784/**
    785  * Return relative path to an uploaded file.
     785 * Returns relative path to an uploaded file.
    786786 *
    787787 * The path is relative to the current upload dir.
     
    814814
    815815/**
    816  * Retrieve all children of the post parent ID.
     816 * Retrieves all children of the post parent ID.
    817817 *
    818818 * Normally, without any enhancements, the children would apply to pages. In the
     
    923923
    924924/**
    925  * Get extended entry info (<!--more-->).
     925 * Gets extended entry info (<!--more-->).
    926926 *
    927927 * There should not be any space after the second dash and before the word
     
    10571057
    10581058/**
    1059  * Retrieve data from a post field based on Post ID.
     1059 * Retrieves data from a post field based on Post ID.
    10601060 *
    10611061 * Examples of the post field will be, 'post_type', 'post_status', 'post_content',
     
    10911091
    10921092/**
    1093  * Retrieve the mime type of an attachment based on the ID.
     1093 * Retrieves the mime type of an attachment based on the ID.
    10941094 *
    10951095 * This function can be used with any post type, but it makes more sense with
     
    11121112
    11131113/**
    1114  * Retrieve the post status based on the post ID.
     1114 * Retrieves the post status based on the post ID.
    11151115 *
    11161116 * If the post ID is of an attachment, then the parent post status will be given
     
    11791179
    11801180/**
    1181  * Retrieve all of the WordPress supported post statuses.
     1181 * Retrieves all of the WordPress supported post statuses.
    11821182 *
    11831183 * Posts have a limited set of valid status values, this provides the
     
    12001200
    12011201/**
    1202  * Retrieve all of the WordPress support page statuses.
     1202 * Retrieves all of the WordPress support page statuses.
    12031203 *
    12041204 * Pages have a limited set of valid status values, this provides the
     
    12201220
    12211221/**
    1222  * Return statuses for privacy requests.
     1222 * Returns statuses for privacy requests.
    12231223 *
    12241224 * @since 4.9.6
     
    12371237
    12381238/**
    1239  * Register a post status. Do not use before init.
     1239 * Registers a post status. Do not use before init.
    12401240 *
    12411241 * A simple function for creating or modifying a post status based on the
     
    13671367
    13681368/**
    1369  * Retrieve a post status object by name.
     1369 * Retrieves a post status object by name.
    13701370 *
    13711371 * @since 3.0.0
     
    13891389
    13901390/**
    1391  * Get a list of post statuses.
     1391 * Gets a list of post statuses.
    13921392 *
    13931393 * @since 3.0.0
     
    14141414
    14151415/**
    1416  * Whether the post type is hierarchical.
     1416 * Determines whether the post type is hierarchical.
    14171417 *
    14181418 * A false return value might also mean that the post type does not exist.
     
    14931493
    14941494/**
    1495  * Get a list of all registered post type objects.
     1495 * Gets a list of all registered post type objects.
    14961496 *
    14971497 * @since 2.9.0
     
    17771777
    17781778/**
    1779  * Build an object with all post type capabilities out of a post type object
     1779 * Builds an object with all post type capabilities out of a post type object
    17801780 *
    17811781 * Post type capabilities use the 'capability_type' argument as a base, if the
     
    18821882
    18831883/**
    1884  * Store or return a list of post type meta caps for map_meta_cap().
     1884 * Stores or returns a list of post type meta caps for map_meta_cap().
    18851885 *
    18861886 * @since 3.1.0
     
    20122012
    20132013/**
    2014  * Build an object with custom-something object (post type, taxonomy) labels
     2014 * Builds an object with custom-something object (post type, taxonomy) labels
    20152015 * out of a custom-something object
    20162016 *
     
    20602060
    20612061/**
    2062  * Add submenus for post types.
     2062 * Adds submenus for post types.
    20632063 *
    20642064 * @access private
     
    21262126
    21272127/**
    2128  * Remove support for a feature from a post type.
     2128 * Removes support for a feature from a post type.
    21292129 *
    21302130 * @since 3.0.0
     
    21422142
    21432143/**
    2144  * Get all the post type features
     2144 * Gets all the post type features
    21452145 *
    21462146 * @since 3.4.0
     
    21622162
    21632163/**
    2164  * Check a post type's support for a given feature.
     2164 * Checks a post type's support for a given feature.
    21652165 *
    21662166 * @since 3.0.0
     
    22012201
    22022202/**
    2203  * Update the post type for the post ID.
     2203 * Updates the post type for the post ID.
    22042204 *
    22052205 * The page or post cache will be cleaned for the post ID.
     
    22712271
    22722272/**
    2273  * Determine whether a post status is considered "viewable".
     2273 * Determines whether a post status is considered "viewable".
    22742274 *
    22752275 * For built-in post statuses such as publish and private, the 'public' value will be evaluated.
     
    23182318
    23192319/**
    2320  * Determine whether a post is publicly viewable.
     2320 * Determines whether a post is publicly viewable.
    23212321 *
    23222322 * Posts are considered publicly viewable if both the post status and post type
     
    25642564
    25652565/**
    2566  * Retrieve post meta fields, based on post ID.
     2566 * Retrieves post meta fields, based on post ID.
    25672567 *
    25682568 * The post meta fields are retrieved from the cache where possible,
     
    25862586
    25872587/**
    2588  * Retrieve meta field names for a post.
     2588 * Retrieves meta field names for a post.
    25892589 *
    25902590 * If there are no meta fields, then nothing (null) will be returned.
     
    26092609
    26102610/**
    2611  * Retrieve values for a custom post field.
     2611 * Retrieves values for a custom post field.
    26122612 *
    26132613 * The parameters must not be considered optional. All of the post meta fields
     
    28822882
    28832883/**
    2884  * Make a post sticky.
     2884 * Makes a post sticky.
    28852885 *
    28862886 * Sticky posts should be displayed at the top of the front page.
     
    29192919
    29202920/**
    2921  * Un-stick a post.
     2921 * Un-sticks a post.
    29222922 *
    29232923 * Sticky posts should be displayed at the top of the front page.
     
    29632963
    29642964/**
    2965  * Return the cache key for wp_count_posts() based on the passed arguments.
     2965 * Returns the cache key for wp_count_posts() based on the passed arguments.
    29662966 *
    29672967 * @since 3.9.0
     
    29872987
    29882988/**
    2989  * Count number of posts of a post type and if user has permissions to view.
     2989 * Counts number of posts of a post type and if user has permissions to view.
    29902990 *
    29912991 * This function provides an efficient method of finding the amount of post's
     
    30523052
    30533053    /**
    3054      * Modify returned post counts by status for the current post type.
     3054     * Modifies returned post counts by status for the current post type.
    30553055     *
    30563056     * @since 3.7.0
     
    30663066
    30673067/**
    3068  * Count number of attachments for the mime type(s).
     3068 * Counts number of attachments for the mime type(s).
    30693069 *
    30703070 * If you set the optional mime_type parameter, then an array will still be
     
    30943094
    30953095    /**
    3096      * Modify returned attachment counts by mime type.
     3096     * Modifies returned attachment counts by mime type.
    30973097     *
    30983098     * @since 3.7.0
     
    31063106
    31073107/**
    3108  * Get default post mime types.
     3108 * Gets default post mime types.
    31093109 *
    31103110 * @since 2.9.0
     
    32103210
    32113211/**
    3212  * Check a MIME-Type against a list.
     3212 * Checks a MIME-Type against a list.
    32133213 *
    32143214 * If the wildcard_mime_types parameter is a string, it must be comma separated
     
    32663266
    32673267/**
    3268  * Convert MIME types into SQL.
     3268 * Converts MIME types into SQL.
    32693269 *
    32703270 * @since 2.5.0
     
    33253325
    33263326/**
    3327  * Trash or delete a post or page.
     3327 * Trashes or deletes a post or page.
    33283328 *
    33293329 * When the post and page is permanently deleted, everything that is tied to
     
    34863486
    34873487/**
    3488  * Reset the page_on_front, show_on_front, and page_for_post settings when
     3488 * Resets the page_on_front, show_on_front, and page_for_post settings when
    34893489 * a linked page is deleted or trashed.
    34903490 *
     
    35173517
    35183518/**
    3519  * Move a post or page to the Trash
     3519 * Moves a post or page to the Trash
    35203520 *
    35213521 * If Trash is disabled, the post or page is permanently deleted.
     
    37573757
    37583758/**
    3759  * Restore comments for a post from the Trash.
     3759 * Restores comments for a post from the Trash.
    37603760 *
    37613761 * @since 2.9.0
     
    38223822
    38233823/**
    3824  * Retrieve the list of categories for a post.
     3824 * Retrieves the list of categories for a post.
    38253825 *
    38263826 * Compatibility layer for themes and plugins. Also an easy layer of abstraction
     
    38513851
    38523852/**
    3853  * Retrieve the tags for a post.
     3853 * Retrieves the tags for a post.
    38543854 *
    38553855 * There is only one default for this function, called 'fields' and by default
     
    38993899
    39003900/**
    3901  * Retrieve a number of recent posts.
     3901 * Retrieves a number of recent posts.
    39023902 *
    39033903 * @since 1.0.0
     
    39523952
    39533953/**
    3954  * Insert or update a post.
     3954 * Inserts or update a post.
    39553955 *
    39563956 * If the $postarr parameter has 'ID' set to a value, then post will be updated.
     
    46924692
    46934693/**
    4694  * Update a post with new post data.
     4694 * Updates a post with new post data.
    46954695 *
    46964696 * The date does not have to be set for drafts. You can set the date and it will
     
    47774777
    47784778/**
    4779  * Publish a post by transitioning the post status.
     4779 * Publishes a post by transitioning the post status.
    47804780 *
    47814781 * @since 2.1.0
     
    48544854
    48554855/**
    4856  * Publish future post and make sure post ID has future post status.
     4856 * Publishes future post and make sure post ID has future post status.
    48574857 *
    48584858 * Invoked by cron 'publish_future_post' event. This safeguard prevents cron
     
    51135113
    51145114/**
    5115  * Truncate a post slug.
     5115 * Truncates a post slug.
    51165116 *
    51175117 * @since 3.6.0
     
    51385138
    51395139/**
    5140  * Add tags to a post.
     5140 * Adds tags to a post.
    51415141 *
    51425142 * @see wp_set_post_tags()
     
    51545154
    51555155/**
    5156  * Set the tags for a post.
     5156 * Sets the tags for a post.
    51575157 *
    51585158 * @since 2.3.0
     
    51725172
    51735173/**
    5174  * Set the terms for a post.
     5174 * Sets the terms for a post.
    51755175 *
    51765176 * @since 2.8.0
     
    52195219
    52205220/**
    5221  * Set categories for a post.
     5221 * Sets categories for a post.
    52225222 *
    52235223 * If no categories are provided, the default category is used.
     
    53995399
    54005400/**
    5401  * Add a URL to those already pinged.
     5401 * Adds a URL to those already pinged.
    54025402 *
    54035403 * @since 1.5.0
     
    54455445
    54465446/**
    5447  * Retrieve enclosures already enclosed for a post.
     5447 * Retrieves enclosures already enclosed for a post.
    54485448 *
    54495449 * @since 1.5.0
     
    54815481
    54825482/**
    5483  * Retrieve URLs already pinged for a post.
     5483 * Retrieves URLs already pinged for a post.
    54845484 *
    54855485 * @since 1.5.0
     
    55115511
    55125512/**
    5513  * Retrieve URLs that need to be pinged.
     5513 * Retrieves URLs that need to be pinged.
    55145514 *
    55155515 * @since 1.5.0
     
    55405540
    55415541/**
    5542  * Do trackbacks for a list of URLs.
     5542 * Does trackbacks for a list of URLs.
    55435543 *
    55445544 * @since 1.0.0
     
    55725572
    55735573/**
    5574  * Get a list of page IDs.
     5574 * Gets a list of page IDs.
    55755575 *
    55765576 * @since 2.0.0
     
    57105710
    57115711/**
    5712  * Retrieve a page given its title.
     5712 * Retrieves a page given its title.
    57135713 *
    57145714 * If more than one post uses the same title, the post with the smallest ID will be returned.
     
    57695769
    57705770/**
    5771  * Identify descendants of a given page ID in a list of page objects.
     5771 * Identifies descendants of a given page ID in a list of page objects.
    57725772 *
    57735773 * Descendants are identified from the `$pages` array passed to the function. No database queries are performed.
     
    58095809
    58105810/**
    5811  * Order the pages with children under parents in a flat list.
     5811 * Orders the pages with children under parents in a flat list.
    58125812 *
    58135813 * It uses auxiliary structure to hold parent-children relationships and
     
    58385838
    58395839/**
    5840  * Traverse and return all the nested children post names of a root page.
     5840 * Traverses and return all the nested children post names of a root page.
    58415841 *
    58425842 * $children contains parent-children relations
     
    58615861
    58625862/**
    5863  * Build the URI path for a page.
     5863 * Builds the URI path for a page.
    58645864 *
    58655865 * Sub pages will be in the "directory" under the parent page post name.
     
    59015901
    59025902/**
    5903  * Retrieve an array of pages (or hierarchical post type items).
     5903 * Retrieves an array of pages (or hierarchical post type items).
    59045904 *
    59055905 * @global wpdb $wpdb WordPress database abstraction object.
     
    62596259
    62606260/**
    6261  * Insert an attachment.
     6261 * Inserts an attachment.
    62626262 *
    62636263 * If you set the 'ID' in the $args parameter, it will mean that you are
     
    63036303
    63046304/**
    6305  * Trash or delete an attachment.
     6305 * Trashes or deletes an attachment.
    63066306 *
    63076307 * When an attachment is permanently deleted, the file will also be removed.
     
    65916591
    65926592/**
    6593  * Retrieve the URL for an attachment.
     6593 * Retrieves the URL for an attachment.
    65946594 *
    65956595 * @since 2.1.0
     
    67006700
    67016701/**
    6702  * Retrieve thumbnail for an attachment.
     6702 * Retrieves thumbnail for an attachment.
    67036703 *
    67046704 * @since 2.1.0
     
    67406740
    67416741/**
    6742  * Retrieve URL for an attachment thumbnail.
     6742 * Retrieves URL for an attachment thumbnail.
    67436743 *
    67446744 * @since 2.1.0
     
    68566856
    68576857/**
    6858  * Retrieve the icon for a MIME type or attachment.
     6858 * Retrieves the icon for a MIME type or attachment.
    68596859 *
    68606860 * @since 2.1.0
     
    69946994
    69956995/**
    6996  * Check for changed slugs for published post objects and save the old slug.
     6996 * Checks for changed slugs for published post objects and save the old slug.
    69976997 *
    69986998 * The function is used when a post object of any type is updated,
     
    70377037
    70387038/**
    7039  * Check for changed dates for published post objects and save the old date.
     7039 * Checks for changed dates for published post objects and save the old date.
    70407040 *
    70417041 * The function is used when a post object of any type is updated,
     
    70837083
    70847084/**
    7085  * Retrieve the private post SQL based on capability.
     7085 * Retrieves the private post SQL based on capability.
    70867086 *
    70877087 * This function provides a standardized way to appropriately select on the
     
    71017101
    71027102/**
    7103  * Retrieve the post SQL based on capability, author, and type.
     7103 * Retrieves the post SQL based on capability, author, and type.
    71047104 *
    71057105 * @since 3.0.0
     
    72217221
    72227222/**
    7223  * Get the most recent time that a post on the site was modified.
     7223 * Gets the most recent time that a post on the site was modified.
    72247224 *
    72257225 * The server timezone is the default and is the difference between GMT and
     
    74257425
    74267426/**
    7427  * Call major cache updating functions for list of Post objects.
     7427 * Calls major cache updating functions for list of Post objects.
    74287428 *
    74297429 * @since 1.5.0
     
    76657665
    76667666/**
    7667  * Check the given subset of the post hierarchy for hierarchy loops.
     7667 * Checks the given subset of the post hierarchy for hierarchy loops.
    76687668 *
    76697669 * Prevents loops from forming and breaks those that it finds. Attached
     
    77577757
    77587758/**
    7759  * Delete auto-drafts for new posts that are > 7 days old.
     7759 * Deletes auto-drafts for new posts that are > 7 days old.
    77607760 *
    77617761 * @since 3.4.0
     
    78137813
    78147814/**
    7815  * Update the custom taxonomies' term counts when a post's status is changed.
     7815 * Updates the custom taxonomies' term counts when a post's status is changed.
    78167816 *
    78177817 * For example, default posts term counts (for custom taxonomies) don't include
     
    79597959
    79607960/**
    7961  * Get all available post MIME types for a given post type.
     7961 * Gets all available post MIME types for a given post type.
    79627962 *
    79637963 * @since 2.5.0
     
    80168016
    80178017/**
    8018  * Retrieve the URL to an original attachment image.
     8018 * Retrieves the URL to an original attachment image.
    80198019 *
    80208020 * Similar to `wp_get_attachment_url()` however some images may have been
     
    80588058
    80598059/**
    8060  * Filter callback which sets the status of an untrashed post to its previous status.
     8060 * Filters callback which sets the status of an untrashed post to its previous status.
    80618061 *
    80628062 * This can be used as a callback on the `wp_untrash_post_status` filter.
Note: See TracChangeset for help on using the changeset viewer.