WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
Built from https://develop.svn.wordpress.org/trunk@25130


git-svn-id: http://core.svn.wordpress.org/trunk@25110 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Dominik Schilling 2013-08-26 20:24:08 +00:00
parent 43016b8948
commit 357f52eed7
2 changed files with 113 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
wp-includes/post.php
View File

@ -1102,6 +1102,7 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
* * Defaults to false. * * Defaults to false.
* * While the default settings of exclude_from_search, publicly_queryable, show_ui, and show_in_nav_menus are * * 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. * 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. * - 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. * * 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(). * - 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. * * 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. * - 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. * * 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. * - 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 true, the post type is shown in its own top level menu.
* * If false, no menu is shown * * 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. * be placed as a sub menu of that.
* * show_ui must be true. * * show_ui must be true.
* * If not set, the default is inherited from show_ui * * 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. * - show_in_admin_bar - Makes this post type available via the admin bar.
* * If not set, the default is inherited from show_in_menu * * If not set, the default is inherited from show_in_menu
* - menu_position - The position in the menu order the post type should appear. * - 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. * * By default the capability_type is used as a base to construct capabilities.
* * You can see accepted values in {@link get_post_type_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. * - 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. * - supports - An alias for calling add_post_type_support() directly. Defaults to title and editor.
* * See {@link add_post_type_support()} for documentation. * * See {@link add_post_type_support()} for documentation.
* - register_meta_box_cb - Provide a callback function that will be called when setting up the * - register_meta_box_cb - Provide a callback function that will be called when setting up the
@ -1166,10 +1166,12 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
* *
* @since 2.9.0 * @since 2.9.0
* @uses $wp_post_types Inserts new post type object into the list * @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. * @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() ) { function register_post_type( $post_type, $args = array() ) {
global $wp_post_types, $wp_rewrite, $wp; global $wp_post_types, $wp_rewrite, $wp;
@ -1179,15 +1181,31 @@ function register_post_type( $post_type, $args = array() ) {
// Args prefixed with an underscore are reserved for internal use. // Args prefixed with an underscore are reserved for internal use.
$defaults = array( $defaults = array(
'labels' => array(), 'description' => '', 'publicly_queryable' => null, 'exclude_from_search' => null, 'labels' => array(),
'capability_type' => 'post', 'capabilities' => array(), 'map_meta_cap' => null, 'description' => '',
'_builtin' => false, '_edit_link' => 'post.php?post=%d', 'hierarchical' => false, 'public' => false,
'public' => false, 'rewrite' => true, 'has_archive' => false, 'query_var' => true, 'hierarchical' => false,
'supports' => array(), 'register_meta_box_cb' => null, 'exclude_from_search' => null,
'taxonomies' => array(), 'show_ui' => null, 'menu_position' => null, 'menu_icon' => 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, 'can_export' => true,
'show_in_nav_menus' => null, 'show_in_menu' => null, 'show_in_admin_bar' => null,
'delete_with_user' => null, '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; $args = (object) $args;
@ -1214,7 +1232,7 @@ function register_post_type( $post_type, $args = array() ) {
if ( null === $args->show_in_admin_bar ) if ( null === $args->show_in_admin_bar )
$args->show_in_admin_bar = true === $args->show_in_menu; $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 ) if ( null === $args->show_in_nav_menus )
$args->show_in_nav_menus = $args->public; $args->show_in_nav_menus = $args->public;
@ -1226,6 +1244,7 @@ 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' ) ) ) if ( empty( $args->capabilities ) && null === $args->map_meta_cap && in_array( $args->capability_type, array( 'post', 'page' ) ) )
$args->map_meta_cap = true; $args->map_meta_cap = true;
// If not set, default to false.
if ( null === $args->map_meta_cap ) if ( null === $args->map_meta_cap )
$args->map_meta_cap = false; $args->map_meta_cap = false;

91
wp-includes/taxonomy.php
View File

@ -270,47 +270,46 @@ function is_taxonomy_hierarchical($taxonomy) {
* *
* Optional $args contents: * 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.
* hierarchical - has some defined purpose at other parts of the API and is a * * By default tag labels are used for non-hierarchical types and category labels for hierarchical ones.
* boolean value. * * You can see accepted values in {@link get_taxonomy_labels()}.
* * - description - A short descriptive summary of what the taxonomy is for. Defaults to blank.
* update_count_callback - works much like a hook, in that it will be called when the count is updated. * - public - If the taxonomy should be publicly queryable; //@TODO not implemented.
* Defaults to _update_post_term_count() for taxonomies attached to post types, which then confirms * * 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. * that the objects are published before counting them.
* Defaults to _update_generic_term_count() for taxonomies attached to other object types, such as links. * * 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!
* *
* 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 * @since 2.3.0
* @uses $wp_taxonomies Inserts new taxonomy object into the list * @uses $wp_taxonomies Inserts new taxonomy object into the list
* @uses $wp Adds query vars * @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 $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. * @return null|WP_Error WP_Error if errors, otherwise null.
*/ */
function register_taxonomy( $taxonomy, $object_type, $args = array() ) { function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
@ -320,18 +319,18 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
$wp_taxonomies = array(); $wp_taxonomies = array();
$defaults = array( $defaults = array(
'labels' => array(),
'description' => '',
'public' => true,
'hierarchical' => false, 'hierarchical' => false,
'update_count_callback' => '', 'show_ui' => null,
'show_in_nav_menus' => null,
'show_tagcloud' => null,
'capabilities' => array(),
'rewrite' => true, 'rewrite' => true,
'query_var' => $taxonomy, 'query_var' => $taxonomy,
'public' => true, 'update_count_callback' => '',
'show_ui' => null,
'show_tagcloud' => null,
'_builtin' => false, '_builtin' => false,
'labels' => array(),
'capabilities' => array(),
'show_in_nav_menus' => null,
'description' => '',
); );
$args = wp_parse_args( $args, $defaults ); $args = wp_parse_args( $args, $defaults );
@ -363,14 +362,16 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
add_permastruct( $taxonomy, "{$args['rewrite']['slug']}/%$taxonomy%", $args['rewrite'] ); 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']; $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'] ) if ( null === $args['show_in_nav_menus'] )
$args['show_in_nav_menus'] = $args['public']; $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']; $args['show_tagcloud'] = $args['show_ui'];
$default_caps = array( $default_caps = array(