Skip to content
Permalink
Browse files

Docs: Correct and improve inline docs relating to caching, terms, met…

…a, and some misc tweaks.

See #47110   


git-svn-id: https://develop.svn.wordpress.org/trunk@45915 602fd350-edb4-49c9-b593-d223f7449a82
  • Loading branch information...
johnbillion committed Aug 30, 2019
1 parent 56d4e7f commit ab7c3658190a556af63ceeab2a816f9db8f45840
@@ -418,7 +418,7 @@ function media_handle_upload( $file_id, $post_id, $post_data = array(), $overrid
* @param int $post_id The post ID the media is associated with.
* @param string $desc Optional. Description of the side-loaded file. Default null.
* @param array $post_data Optional. Post data to override. Default empty array.
* @return int|object The ID of the attachment or a WP_Error on failure.
* @return int|WP_Error The ID of the attachment or a WP_Error on failure.
*/
function media_handle_sideload( $file_array, $post_id, $desc = null, $post_data = array() ) {
$overrides = array( 'test_form' => false );
@@ -179,7 +179,7 @@ public static function fill_query_vars( $args ) {
* @type int $number Number of users to limit the query for. Can be used in
* conjunction with pagination. Value -1 (all) is supported, but
* should be used with caution on larger sites.
* Default empty (all users).
* Default -1 (all users).
* @type int $paged When used with number, defines the page of results to return.
* Default 1.
* @type bool $count_total Whether to count the total number of users found. If pagination
@@ -877,8 +877,8 @@ function delete_metadata_by_mid( $meta_type, $meta_id ) {
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
* @param int|array $object_ids Array or comma delimited list of object IDs to update cache for
* @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
* @param string|int[] $object_ids Array or comma delimited list of object IDs to update cache for.
* @return array|false Metadata cache for the specified objects, or false on failure.
*/
function update_meta_cache( $meta_type, $object_ids ) {
@@ -912,7 +912,7 @@ function update_meta_cache( $meta_type, $object_ids ) {
* @since 5.0.0
*
* @param mixed $check Whether to allow updating the meta cache of the given type.
* @param array $object_ids Array of object IDs to update the meta cache for.
* @param int[] $object_ids Array of object IDs to update the meta cache for.
*/
$check = apply_filters( "update_{$meta_type}_metadata_cache", null, $object_ids );
if ( null !== $check ) {
@@ -1266,7 +1266,7 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
* If not set, the default is inherited from $public.
* @type bool $show_ui Whether to generate and allow a UI for managing this post type in the
* admin. Default is value of $public.
* @type bool $show_in_menu Where to show the post type in the admin menu. To work, $show_ui
* @type bool|string $show_in_menu Where to show the post type in the admin menu. To work, $show_ui
* must be true. If true, the post type is shown in its own top level
* menu. If false, no menu is shown. If a string of an existing top
* level menu (eg. 'tools.php' or 'edit.php?post_type=page'), the post
@@ -6416,7 +6416,7 @@ function _get_last_post_time( $timezone, $field, $post_type = 'any' ) {
*
* @since 1.5.1
*
* @param array $posts Array of post objects (passed by reference).
* @param WP_Post[] $posts Array of post objects (passed by reference).
*/
function update_post_cache( &$posts ) {
if ( ! $posts ) {
@@ -6493,10 +6493,10 @@ function clean_post_cache( $post ) {
*
* @since 1.5.0
*
* @param array $posts Array of Post objects
* @param string $post_type Optional. Post type. Default 'post'.
* @param bool $update_term_cache Optional. Whether to update the term cache. Default true.
* @param bool $update_meta_cache Optional. Whether to update the meta cache. Default true.
* @param WP_Post[] $posts Array of Post objects
* @param string $post_type Optional. Post type. Default 'post'.
* @param bool $update_term_cache Optional. Whether to update the term cache. Default true.
* @param bool $update_meta_cache Optional. Whether to update the meta cache. Default true.
*/
function update_post_caches( &$posts, $post_type = 'post', $update_term_cache = true, $update_meta_cache = true ) {
// No point in doing all this work if we didn't match any posts.
@@ -6548,7 +6548,7 @@ function update_post_caches( &$posts, $post_type = 'post', $update_term_cache =
*
* @since 2.1.0
*
* @param array $post_ids List of post IDs.
* @param int[] $post_ids Array of post IDs.
* @return array|false Returns false if there is nothing to update or an array
* of metadata.
*/
@@ -214,10 +214,10 @@ function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' )
*
* @global array $wp_taxonomies The registered taxonomies.
*
* @param array|string|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
* @param string $output Optional. The type of output to return in the array. Accepts either
* taxonomy 'names' or 'objects'. Default 'names'.
* @return array The names of all taxonomy of $object_type.
* @param string|string[]|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
* @param string $output Optional. The type of output to return in the array. Accepts either
* 'names' or 'objects'. Default 'names'.
* @return string[]|WP_Taxonomy[] The names or objects of all taxonomies of `$object_type`.
*/
function get_object_taxonomies( $object, $output = 'names' ) {
global $wp_taxonomies;
@@ -1959,11 +1959,11 @@ function wp_delete_category( $cat_ID ) {
* 'all_with_object_id', an array of `WP_Term` objects will be returned.
* @since 4.7.0 Refactored to use WP_Term_Query, and to support any WP_Term_Query arguments.
*
* @param int|array $object_ids The ID(s) of the object(s) to retrieve.
* @param string|array $taxonomies The taxonomies to retrieve terms from.
* @param array|string $args See WP_Term_Query::__construct() for supported arguments.
* @param int|int[] $object_ids The ID(s) of the object(s) to retrieve.
* @param string|string[] $taxonomies The taxonomy names to retrieve terms from.
* @param array|string $args See WP_Term_Query::__construct() for supported arguments.
* @return array|WP_Error The requested term data or empty array if no terms found.
* WP_Error if any of the $taxonomies don't exist.
* WP_Error if any of the taxonomies don't exist.
*/
function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
if ( empty( $object_ids ) || empty( $taxonomies ) ) {
@@ -1992,10 +1992,10 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
*
* @since 4.9.0
*
* @param array $args An array of arguments for retrieving terms for the given object(s).
* See {@see wp_get_object_terms()} for details.
* @param int|array $object_ids Object ID or array of IDs.
* @param string|array $taxonomies The taxonomies to retrieve terms from.
* @param array $args An array of arguments for retrieving terms for the given object(s).
* See {@see wp_get_object_terms()} for details.
* @param int[] $object_ids Array of object IDs.
* @param string[] $taxonomies Array of taxonomy names to retrieve terms from.
*/
$args = apply_filters( 'wp_get_object_terms_args', $args, $object_ids, $taxonomies );
@@ -2039,11 +2039,11 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
*
* @since 4.2.0
*
* @param array $terms An array of terms for the given object or objects.
* @param array $object_ids Array of object IDs for which `$terms` were retrieved.
* @param array $taxonomies Array of taxonomies from which `$terms` were retrieved.
* @param array $args An array of arguments for retrieving terms for the given
* object(s). See wp_get_object_terms() for details.
* @param array $terms Array of terms for the given object or objects.
* @param int[] $object_ids Array of object IDs for which terms were retrieved.
* @param string[] $taxonomies Array of taxonomy names from which terms were retrieved.
* @param array $args Array of arguments for retrieving terms for the given
* object(s). See wp_get_object_terms() for details.
*/
$terms = apply_filters( 'get_object_terms', $terms, $object_ids, $taxonomies, $args );
@@ -2058,11 +2058,11 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
*
* @since 2.8.0
*
* @param array $terms An array of terms for the given object or objects.
* @param int|array $object_ids Object ID or array of IDs.
* @param string $taxonomies SQL-formatted (comma-separated and quoted) list of taxonomy names.
* @param array $args An array of arguments for retrieving terms for the given object(s).
* See wp_get_object_terms() for details.
* @param array $terms Array of terms for the given object or objects.
* @param int[] $object_ids Array of object IDs for which terms were retrieved.
* @param string[] $taxonomies Array of taxonomy names from which terms were retrieved.
* @param array $args Array of arguments for retrieving terms for the given
* object(s). See wp_get_object_terms() for details.
*/
return apply_filters( 'wp_get_object_terms', $terms, $object_ids, $taxonomies, $args );
}
@@ -2421,7 +2421,7 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
* empty value will remove all related terms.
* @param string $taxonomy The context in which to relate the term to the object.
* @param bool $append Optional. If false will delete difference of terms. Default false.
* @return array|WP_Error Term taxonomy IDs of the affected terms.
* @return array|WP_Error Term taxonomy IDs of the affected terms or WP_Error on failure.
*/
function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
global $wpdb;
@@ -3365,8 +3365,8 @@ function get_object_term_cache( $id, $taxonomy ) {
*
* @since 2.3.0
*
* @param string|array $object_ids Comma-separated list or array of term object IDs.
* @param array|string $object_type The taxonomy object type.
* @param string|int[] $object_ids Comma-separated list or array of term object IDs.
* @param string|string[] $object_type The taxonomy object type or array of the same.
* @return void|false False if all of the terms in `$object_ids` are already cached.
*/
function update_object_term_cache( $object_ids, $object_type ) {

0 comments on commit ab7c365

Please sign in to comment.
You can’t perform that action at this time.