Document globals in bundled themes #5920
Conversation
- `$wp_version` for `twentyten_setup()`, `gallery_style` backward compatibility filter - `$comment` for `twentyten_comment()` - matches "comment arguments" in `twentyeleven_comment()`
Adds notation for `$page` and `$paged` in multi-line comment (not docblock) before `wp_title()`
- `$wp_version` for `twentyeleven_setup()` - `$wp_query` for `twentyeleven_content_nav()` - `$comment` for `twentyeleven_comment()`
Adds notes for `$page` and `$paged` in multi-line comment (not docblock) before `wp_title()`
Adds docblock-style notation for `$feature_class`
Adds note about `$more` in a multi-line comment
Additions to docblocks: - `$wp_version` for `twentytwelve_setup()` and `twentytwelve_resource_hints()` - `$wp_styles` for `twentytwelve_scripts_styles()` - `$paged` and `$page` for `twentytwelve_wp_title()` - `$wp_query` for `twentytwelve_content_nav( )` - `$comment` for `twentytwelve_comment()` plus parameter information from Twenty Eleven - `$content_width` for `twentytwelve_content_width()`
Additions to docblocks: - `$wp_version` for `back-compat.php`, `twentythirteen_setup()`, and `twentythirteen_resource_hints()` - `$wp_query` for `twentythirteen_paging_nav()`
Adds global notation for `$wp_version` in `twentythirteen_upgrade_notice()`, `twentythirteen_customize()`, and `twentythirteen_preview()`
- `$wp_version` for `back-compat.php`, `twentyfourteen_setup()`, `twentyfourteen_resource_hints()`, `twentyfourteen_list_authors()` - `$content_width` for `twentyfourteen_content_width()` - `$pagenow` for `twentyfourteen_body_classes()` and `featured-content.php`
Adds global notation for `$wp_version` in `twentyfourteen_upgrade_notice()`, `twentyfourteen_customize()`, and `twentyfourteen_preview()`
Adds global notation for `$typenow` in `twentyfourteen_contextual_help()`
Adds global notation for `$content_width` and `$more` in `widget()`
Adds notations of global variable `$wp_version` for `back-compat.php`, `twentyfifteen_setup()`, and `twentyfifteen_resource_hints()`
Adds global notation for `$wp_version` in `twentyfifteen_upgrade_notice()`, `twentyfifteen_customize()`, and `twentyfifteen_preview()`
- Adds notation of global variable `$wp_version` for `back-compat.php` and `twentysixteen_setup()` - Adds description to `$content_width` for `twentysixteen_content_width()`
- Adds notation of global variable `$wp_version` for `back-compat.php` - Adds `since` and notation of global variable `$content_width` for `twentyseventeen_setup()` - Adds description to `$content_width` for `twentyseventeen_content_width()`
Adds docblock-style note for `$twentyseventeencounter`
Adds notation of global variable `$wp_version` for `back-compat.php`
- Adds notation of global variables `$content_width` and `$wp_version` for `twentytwenty_theme_support()` - Adds docblock-style notation for global variable `$wp_version` when determining how to enqueue block styles
- Changes single-line comment to docblock-style for `back-compat.php` so it documents `$wp_version` - Adds notation about `$is_IE` for `twenty_twenty_one_setup()` and capitalizes Internet Explorer
| @@ -741,6 +745,8 @@ function twentyeleven_footer_sidebar_class() { | |||
| * | |||
| * @since Twenty Eleven 1.0 | |||
| * | |||
| * @global WP_Comment $comment Global comment object. | |||
There was a problem hiding this comment.
58715.2.patch documented the $comment global in twentyten_comment(), twentyeleven_comment() and twentytwelve_comment(). This seems odd when $comment is also a parameter, though I do not know of a reason why these functions cannot document it as both global and parameter.
| * | ||
| * @param WP_Comment $comment The comment object. | ||
| * @param array $args An array of comment arguments. @see get_comment_reply_link() | ||
| * @param int $depth The depth of the comment. |
There was a problem hiding this comment.
twentytwelve_comment() did not document $comment as either a global or one of the parameters
| @@ -67,6 +67,9 @@ public function enqueue_scripts() { | |||
| * | |||
| * @since Twenty Fourteen 1.0 | |||
| * | |||
| * @global int $content_width Content width. | |||
| * @global int $more | |||
There was a problem hiding this comment.
59101-twentyfifteen.patch and the Core register_globals() function describe the $more variable as "Only set, if single page or post." However, that optional description does not make sense to me in the context of the Twenty_Fourteen_Ephemera_Widget::widget() method, which sets $GLOBALS['more'] = 0.
| @@ -208,7 +208,11 @@ | |||
| if ( $recent->have_posts() ) : | |||
| $recent->the_post(); | |||
|
|
|||
| // Set $more to 0 in order to only get the first part of the post. | |||
| /* | |||
There was a problem hiding this comment.
single-line comment style changed to multi-line (should it be docblock or edited another way?)
Test using WordPress PlaygroundThe changes in this pull request can previewed and tested using a WordPress Playground instance. WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser. Some things to be aware of
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
| @@ -7,6 +7,9 @@ | |||
| * @since Twenty Eleven 1.0 | |||
| */ | |||
|
|
|||
| /** | |||
| * @global string $feature_class Classes for post container of featured posts. | |||
| */ | |||
There was a problem hiding this comment.
Twenty Twenty documents $wp_query in the index.php template using a similar short docblock. Is this the best way for templates such as content-featured.php or Twenty Seventeen's content-front-page-panels.php to document their globals?
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
| @@ -33,7 +33,7 @@ function twentynineteen_switch_theme() { | |||
| * | |||
| * @since Twenty Nineteen 1.0.0 | |||
| * | |||
| * @global string $wp_version WordPress version. | |||
| * @global string $wp_version The WordPress version string. | |||
There was a problem hiding this comment.
I had originally added new tags to match "WordPress version" in the back-compat files for consistency just within the themes collection. Because other Core files repeatedly describe $wp_version as "The WordPress version string," the themes match that instead now.
Adds documentation for global variables in all of the classic bundled themes.
Props upadalavipul, shailu25, rajinsharwar, audrasjb, viralsampat
Trac 58715
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.