From d0365d13834d681e0598ac0ae651a5a1c6f6f3be Mon Sep 17 00:00:00 2001 From: "Dominik Schilling (ocean90)" Date: Mon, 26 Aug 2013 20:23:34 +0000 Subject: [PATCH] Improve inline docs for register_post_type() and register_taxonomy(). * register_taxonomy: Use the same doc format for the associative array arg as used for register_post_type() * register_taxonomy: Improve docs for _builtin, capabilities, hierarchical and rewrite args * register_taxonomy: Use the same order in $defaults as in docblock * register_taxonomy: Replace is_null with null ===, to be consistent * register_post_type: Use the same order in $defaults as in docblock * register_post_type: Improve docs for @uses and default fallbacks And while we're on it: Whitespaces. fixes #25150. git-svn-id: https://develop.svn.wordpress.org/trunk@25130 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/post.php | 83 ++++++++++++++--------- src/wp-includes/taxonomy.php | 123 ++++++++++++++++++----------------- 2 files changed, 113 insertions(+), 93 deletions(-) diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php index 02be1b7b0a..55a09aefa9 100644 --- a/src/wp-includes/post.php +++ b/src/wp-includes/post.php @@ -1102,6 +1102,7 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' ) * * Defaults to false. * * While the default settings of exclude_from_search, publicly_queryable, show_ui, and show_in_nav_menus are * inherited from public, each does not rely on this relationship and controls a very specific intention. + * - hierarchical - Whether the post type is hierarchical (e.g. page). Defaults to false. * - exclude_from_search - Whether to exclude posts with this post type from front end search results. * * If not set, the opposite of public's current value is used. * - publicly_queryable - Whether queries can be performed on the front end for the post type as part of parse_request(). @@ -1111,8 +1112,6 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' ) * * If not set, the default is inherited from public. * - show_ui - Whether to generate a default UI for managing this post type in the admin. * * If not set, the default is inherited from public. - * - show_in_nav_menus - Makes this post type available for selection in navigation menus. - * * If not set, the default is inherited from public. * - show_in_menu - Where to show the post type in the admin menu. * * If true, the post type is shown in its own top level menu. * * If false, no menu is shown @@ -1120,6 +1119,8 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' ) * be placed as a sub menu of that. * * show_ui must be true. * * If not set, the default is inherited from show_ui + * - show_in_nav_menus - Makes this post type available for selection in navigation menus. + * * If not set, the default is inherited from public. * - show_in_admin_bar - Makes this post type available via the admin bar. * * If not set, the default is inherited from show_in_menu * - menu_position - The position in the menu order the post type should appear. @@ -1133,7 +1134,6 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' ) * * By default the capability_type is used as a base to construct capabilities. * * You can see accepted values in {@link get_post_type_capabilities()}. * - map_meta_cap - Whether to use the internal default meta capability handling. Defaults to false. - * - hierarchical - Whether the post type is hierarchical (e.g. page). Defaults to false. * - supports - An alias for calling add_post_type_support() directly. Defaults to title and editor. * * See {@link add_post_type_support()} for documentation. * - register_meta_box_cb - Provide a callback function that will be called when setting up the @@ -1166,37 +1166,55 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' ) * * @since 2.9.0 * @uses $wp_post_types Inserts new post type object into the list + * @uses $wp_rewrite Gets default feeds + * @uses $wp Adds query vars * - * @param string $post_type Post type key, must not exceed 20 characters + * @param string $post_type Post type key, must not exceed 20 characters. * @param array|string $args See optional args description above. - * @return object|WP_Error the registered post type object, or an error object + * @return object|WP_Error the registered post type object, or an error object. */ function register_post_type( $post_type, $args = array() ) { global $wp_post_types, $wp_rewrite, $wp; - if ( !is_array($wp_post_types) ) + if ( ! is_array( $wp_post_types ) ) $wp_post_types = array(); // Args prefixed with an underscore are reserved for internal use. $defaults = array( - 'labels' => array(), 'description' => '', 'publicly_queryable' => null, 'exclude_from_search' => null, - 'capability_type' => 'post', 'capabilities' => array(), 'map_meta_cap' => null, - '_builtin' => false, '_edit_link' => 'post.php?post=%d', 'hierarchical' => false, - 'public' => false, 'rewrite' => true, 'has_archive' => false, 'query_var' => true, - 'supports' => array(), 'register_meta_box_cb' => null, - 'taxonomies' => array(), 'show_ui' => null, 'menu_position' => null, 'menu_icon' => null, - 'can_export' => true, - 'show_in_nav_menus' => null, 'show_in_menu' => null, 'show_in_admin_bar' => null, - 'delete_with_user' => null, + 'labels' => array(), + 'description' => '', + 'public' => false, + 'hierarchical' => false, + 'exclude_from_search' => null, + 'publicly_queryable' => null, + 'show_ui' => null, + 'show_in_menu' => null, + 'show_in_nav_menus' => null, + 'show_in_admin_bar' => null, + 'menu_position' => null, + 'menu_icon' => null, + 'capability_type' => 'post', + 'capabilities' => array(), + 'map_meta_cap' => null, + 'supports' => array(), + 'register_meta_box_cb' => null, + 'taxonomies' => array(), + 'has_archive' => false, + 'rewrite' => true, + 'query_var' => true, + 'can_export' => true, + 'delete_with_user' => null, + '_builtin' => false, + '_edit_link' => 'post.php?post=%d', ); - $args = wp_parse_args($args, $defaults); + $args = wp_parse_args( $args, $defaults ); $args = (object) $args; - $post_type = sanitize_key($post_type); + $post_type = sanitize_key( $post_type ); $args->name = $post_type; if ( strlen( $post_type ) > 20 ) - return new WP_Error( 'post_type_too_long', __( 'Post types cannot exceed 20 characters in length' ) ); + return new WP_Error( 'post_type_too_long', __( 'Post types cannot exceed 20 characters in length' ) ); // If not set, default to the setting for public. if ( null === $args->publicly_queryable ) @@ -1214,7 +1232,7 @@ function register_post_type( $post_type, $args = array() ) { if ( null === $args->show_in_admin_bar ) $args->show_in_admin_bar = true === $args->show_in_menu; - // Whether to show this type in nav-menus.php. Defaults to the setting for public. + // If not set, default to the setting for public. if ( null === $args->show_in_nav_menus ) $args->show_in_nav_menus = $args->public; @@ -1226,32 +1244,33 @@ function register_post_type( $post_type, $args = array() ) { if ( empty( $args->capabilities ) && null === $args->map_meta_cap && in_array( $args->capability_type, array( 'post', 'page' ) ) ) $args->map_meta_cap = true; + // If not set, default to false. if ( null === $args->map_meta_cap ) $args->map_meta_cap = false; $args->cap = get_post_type_capabilities( $args ); - unset($args->capabilities); + unset( $args->capabilities ); if ( is_array( $args->capability_type ) ) $args->capability_type = $args->capability_type[0]; - if ( ! empty($args->supports) ) { - add_post_type_support($post_type, $args->supports); - unset($args->supports); + if ( ! empty( $args->supports ) ) { + add_post_type_support( $post_type, $args->supports ); + unset( $args->supports ); } elseif ( false !== $args->supports ) { // Add default features - add_post_type_support($post_type, array('title', 'editor')); + add_post_type_support( $post_type, array( 'title', 'editor' ) ); } - if ( false !== $args->query_var && !empty($wp) ) { + if ( false !== $args->query_var && ! empty( $wp ) ) { if ( true === $args->query_var ) $args->query_var = $post_type; else - $args->query_var = sanitize_title_with_dashes($args->query_var); - $wp->add_query_var($args->query_var); + $args->query_var = sanitize_title_with_dashes( $args->query_var ); + $wp->add_query_var( $args->query_var ); } - if ( false !== $args->rewrite && ( is_admin() || '' != get_option('permalink_structure') ) ) { + if ( false !== $args->rewrite && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) { if ( ! is_array( $args->rewrite ) ) $args->rewrite = array(); if ( empty( $args->rewrite['slug'] ) ) @@ -1270,9 +1289,9 @@ function register_post_type( $post_type, $args = array() ) { } if ( $args->hierarchical ) - add_rewrite_tag("%$post_type%", '(.+?)', $args->query_var ? "{$args->query_var}=" : "post_type=$post_type&name="); + add_rewrite_tag( "%$post_type%", '(.+?)', $args->query_var ? "{$args->query_var}=" : "post_type=$post_type&name=" ); else - add_rewrite_tag("%$post_type%", '([^/]+)', $args->query_var ? "{$args->query_var}=" : "post_type=$post_type&name="); + add_rewrite_tag( "%$post_type%", '([^/]+)', $args->query_var ? "{$args->query_var}=" : "post_type=$post_type&name=" ); if ( $args->has_archive ) { $archive_slug = $args->has_archive === true ? $args->rewrite['slug'] : $args->has_archive; @@ -1297,12 +1316,12 @@ function register_post_type( $post_type, $args = array() ) { } if ( $args->register_meta_box_cb ) - add_action('add_meta_boxes_' . $post_type, $args->register_meta_box_cb, 10, 1); + add_action( 'add_meta_boxes_' . $post_type, $args->register_meta_box_cb, 10, 1 ); $args->labels = get_post_type_labels( $args ); $args->label = $args->labels->name; - $wp_post_types[$post_type] = $args; + $wp_post_types[ $post_type ] = $args; add_action( 'future_' . $post_type, '_future_post_hook', 5, 2 ); diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index 2758472c68..66f872d1ef 100644 --- a/src/wp-includes/taxonomy.php +++ b/src/wp-includes/taxonomy.php @@ -270,89 +270,88 @@ function is_taxonomy_hierarchical($taxonomy) { * * Optional $args contents: * - * label - Name of the taxonomy shown in the menu. Usually plural. If not set, labels['name'] will be used. + * - label - Name of the taxonomy shown in the menu. Usually plural. If not set, labels['name'] will be used. + * - labels - An array of labels for this taxonomy. + * * By default tag labels are used for non-hierarchical types and category labels for hierarchical ones. + * * You can see accepted values in {@link get_taxonomy_labels()}. + * - description - A short descriptive summary of what the taxonomy is for. Defaults to blank. + * - public - If the taxonomy should be publicly queryable; //@TODO not implemented. + * * Defaults to true. + * - hierarchical - Whether the taxonomy is hierarchical (e.g. category). Defaults to false. + * - show_ui -Whether to generate a default UI for managing this taxonomy in the admin. + * * If not set, the default is inherited from public. + * - show_in_nav_menus - Makes this taxonomy available for selection in navigation menus. + * * If not set, the default is inherited from public. + * - show_tagcloud - Whether to list the taxonomy in the Tag Cloud Widget. + * * If not set, the default is inherited from show_ui. + * - capabilities - Array of capabilities for this taxonomy. + * * You can see accepted values in this function. + * - rewrite - Triggers the handling of rewrites for this taxonomy. Defaults to true, using $taxonomy as slug. + * * To prevent rewrite, set to false. + * * To specify rewrite rules, an array can be passed with any of these keys + * * 'slug' => string Customize the permastruct slug. Defaults to $taxonomy key + * * 'with_front' => bool Should the permastruct be prepended with WP_Rewrite::$front. Defaults to true. + * * 'hierarchical' => bool Either hierarchical rewrite tag or not. Defaults to false. + * * 'ep_mask' => const Assign an endpoint mask. + * * If not specified, defaults to EP_NONE. + * - query_var - Sets the query_var key for this taxonomy. Defaults to $taxonomy key + * * If false, a taxonomy cannot be loaded at ?{query_var}={term_slug} + * * If specified as a string, the query ?{query_var_string}={term_slug} will be valid. + * - update_count_callback - Works much like a hook, in that it will be called when the count is updated. + * * Defaults to _update_post_term_count() for taxonomies attached to post types, which then confirms + * that the objects are published before counting them. + * * Defaults to _update_generic_term_count() for taxonomies attached to other object types, such as links. + * - _builtin - true if this taxonomy is a native or "built-in" taxonomy. THIS IS FOR INTERNAL USE ONLY! * - * hierarchical - has some defined purpose at other parts of the API and is a - * boolean value. - * - * update_count_callback - works much like a hook, in that it will be called when the count is updated. - * Defaults to _update_post_term_count() for taxonomies attached to post types, which then confirms - * that the objects are published before counting them. - * Defaults to _update_generic_term_count() for taxonomies attached to other object types, such as links. - * - * rewrite - false to prevent rewrite, or array('slug'=>$slug) to customize - * permastruct; default will use $taxonomy as slug. - * - * query_var - false to prevent queries, or string to customize query var - * (?$query_var=$term); default will use $taxonomy as query var. - * - * public - If the taxonomy should be publicly queryable; //@TODO not implemented. - * defaults to true. - * - * show_ui - If the WordPress UI admin tags UI should apply to this taxonomy; - * defaults to public. - * - * show_in_nav_menus - true makes this taxonomy available for selection in navigation menus. - * Defaults to public. - * - * show_tagcloud - false to prevent the taxonomy being listed in the Tag Cloud Widget; - * defaults to show_ui which defaults to public. - * - * labels - An array of labels for this taxonomy. You can see accepted values in {@link get_taxonomy_labels()}. By default tag labels are used for non-hierarchical types and category labels for hierarchical ones. - * - * description - A short descriptive summary of what the taxonomy is for. Defaults to blank. - * - * @package WordPress - * @subpackage Taxonomy * @since 2.3.0 * @uses $wp_taxonomies Inserts new taxonomy object into the list * @uses $wp Adds query vars * - * @param string $taxonomy Name of taxonomy object + * @param string $taxonomy Taxonomy key, must not exceed 32 characters. * @param array|string $object_type Name of the object type for the taxonomy object. - * @param array|string $args See above description for the two keys values. + * @param array|string $args See optional args description above. * @return null|WP_Error WP_Error if errors, otherwise null. */ function register_taxonomy( $taxonomy, $object_type, $args = array() ) { global $wp_taxonomies, $wp; - if ( ! is_array($wp_taxonomies) ) + if ( ! is_array( $wp_taxonomies ) ) $wp_taxonomies = array(); $defaults = array( - 'hierarchical' => false, + 'labels' => array(), + 'description' => '', + 'public' => true, + 'hierarchical' => false, + 'show_ui' => null, + 'show_in_nav_menus' => null, + 'show_tagcloud' => null, + 'capabilities' => array(), + 'rewrite' => true, + 'query_var' => $taxonomy, 'update_count_callback' => '', - 'rewrite' => true, - 'query_var' => $taxonomy, - 'public' => true, - 'show_ui' => null, - 'show_tagcloud' => null, - '_builtin' => false, - 'labels' => array(), - 'capabilities' => array(), - 'show_in_nav_menus' => null, - 'description' => '', + '_builtin' => false, ); - $args = wp_parse_args($args, $defaults); + $args = wp_parse_args( $args, $defaults ); if ( strlen( $taxonomy ) > 32 ) return new WP_Error( 'taxonomy_too_long', __( 'Taxonomies cannot exceed 32 characters in length' ) ); - if ( false !== $args['query_var'] && !empty($wp) ) { + if ( false !== $args['query_var'] && ! empty( $wp ) ) { if ( true === $args['query_var'] ) $args['query_var'] = $taxonomy; else - $args['query_var'] = sanitize_title_with_dashes($args['query_var']); - $wp->add_query_var($args['query_var']); + $args['query_var'] = sanitize_title_with_dashes( $args['query_var'] ); + $wp->add_query_var( $args['query_var'] ); } - if ( false !== $args['rewrite'] && ( is_admin() || '' != get_option('permalink_structure') ) ) { - $args['rewrite'] = wp_parse_args($args['rewrite'], array( - 'slug' => sanitize_title_with_dashes($taxonomy), + if ( false !== $args['rewrite'] && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) { + $args['rewrite'] = wp_parse_args( $args['rewrite'], array( + 'slug' => sanitize_title_with_dashes( $taxonomy ), 'with_front' => true, 'hierarchical' => false, 'ep_mask' => EP_NONE, - )); + ) ); if ( $args['hierarchical'] && $args['rewrite']['hierarchical'] ) $tag = '(.+?)'; @@ -363,14 +362,16 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) { add_permastruct( $taxonomy, "{$args['rewrite']['slug']}/%$taxonomy%", $args['rewrite'] ); } - if ( is_null($args['show_ui']) ) + // If not set, default to the setting for public. + if ( null === $args['show_ui'] ) $args['show_ui'] = $args['public']; - // Whether to show this type in nav-menus.php. Defaults to the setting for public. + // If not set, default to the setting for public. if ( null === $args['show_in_nav_menus'] ) $args['show_in_nav_menus'] = $args['public']; - if ( is_null($args['show_tagcloud']) ) + // If not set, default to the setting for show_ui. + if ( null === $args['show_tagcloud'] ) $args['show_tagcloud'] = $args['show_ui']; $default_caps = array( @@ -383,15 +384,15 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) { unset( $args['capabilities'] ); $args['name'] = $taxonomy; - $args['object_type'] = array_unique( (array)$object_type ); + $args['object_type'] = array_unique( (array) $object_type ); $args['labels'] = get_taxonomy_labels( (object) $args ); $args['label'] = $args['labels']->name; - $wp_taxonomies[$taxonomy] = (object) $args; + $wp_taxonomies[ $taxonomy ] = (object) $args; // register callback handling for metabox - add_filter('wp_ajax_add-' . $taxonomy, '_wp_ajax_add_hierarchical_term'); + add_filter( 'wp_ajax_add-' . $taxonomy, '_wp_ajax_add_hierarchical_term' ); do_action( 'registered_taxonomy', $taxonomy, $object_type, $args ); }