Make WordPress Core

Opened 8 months ago

Closed 5 months ago

Last modified 4 months ago

#60021 closed task (blessed) (fixed)

Document global $link & $wpdb in wp-includes/bookmark.php & wp-includes/class-wp-user.php files.

Reported by: upadalavipul's profile upadalavipul Owned by: sergeybiryukov's profile SergeyBiryukov
Milestone: 6.5 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs, coding-standards Cc:

Description

I have reviewed the below file code and found that we are using a global $link and $wpdb variable. but they do not mention it in the function comment. So I think we need to improve the function comment code.

Files:

  1. trunk/wp-includes/bookmark.php
  2. wp-includes/class-wp-user.php

Attachments (24)

60021.patch (1.0 KB) - added by upadalavipul 8 months ago.
60021.2.patch (3.2 KB) - added by viralsampat 8 months ago.
I have checked above mentioned issue and founds few files. Here, I have added its patch.
60021.3.patch (353 bytes) - added by upadalavipul 8 months ago.
60021.4.patch (1.2 KB) - added by upadalavipul 8 months ago.
60021.5.patch (2.0 KB) - added by viralsampat 8 months ago.
I have checked above mentioned issue and founds few files. Here, I have added its patch.
60021.6.patch (1.1 KB) - added by upadalavipul 8 months ago.
60021.diff (1.1 KB) - added by shailu25 8 months ago.
Added Since before global & added global before param in documentation as per php coding standard in src/wp-includes/admin-bar.php
60021.7.patch (1.8 KB) - added by viralsampat 7 months ago.
I have checked above mentioned issue and founds few files. Here, I have added its patch.
60021.8.patch (1.6 KB) - added by upadalavipul 7 months ago.
60021.9.patch (1.1 KB) - added by viralsampat 7 months ago.
I have checked above mentioned issue and founds few files. Here, I have added its patch.
60021.10.patch (475 bytes) - added by upadalavipul 7 months ago.
60021.11.patch (1.0 KB) - added by shailu25 7 months ago.
I have Added Global Documentation in wp-includes/rss.php & wp-includes/widgets.php
60021.12.patch (550 bytes) - added by upadalavipul 7 months ago.
60021.13.patch (682 bytes) - added by viralsampat 7 months ago.
I have checked above mentioned issue and founds few files. Here, I have added its patch.
60021.14.patch (849 bytes) - added by upadalavipul 7 months ago.
60021.15.patch (995 bytes) - added by upadalavipul 7 months ago.
60021.16.patch (405 bytes) - added by upadalavipul 7 months ago.
60021.17.patch (7.0 KB) - added by shailu25 7 months ago.
I have Added Global Documentation for Twenty Thirteen theme, Twenty Fourteen theme & Twenty Fifteen theme.
60021.18.patch (1.5 KB) - added by shailu25 7 months ago.
Added Global Documentations
60021.19.patch (1.4 KB) - added by viralsampat 7 months ago.
I have checked above mentioned issue and founds few files. Here, I have added its patch.
60021.wp-settings.patch (1.3 KB) - added by sabernhardt 5 months ago.
adds docblocks for $table_prefix, $wp_embed and $wp_plugin_paths
60021.20.patch (2.3 KB) - added by viralsampat 5 months ago.
I have checked above mentioned issue and founds few files. Here, I have added its patch.
60021.21.patch (2.7 KB) - added by viralsampat 5 months ago.
I have checked above mentioned issue and founds few files. Here, I have added its patch.
60021.23.patch (641 bytes) - added by viralsampat 4 months ago.
I have worked on above mentioned issue and removed unused global variable from wp-includes.

Download all attachments as: .zip

Change History (56)

@upadalavipul
8 months ago

#1 @mukesh27
8 months ago

  • Keywords has-patch added

Thanks for the ticket and patch!

There are many other places in code that miss similar global declaration could you please ass all in single patch so we can easy commit it otherwise we get similar ticket for other places.

Make sure to update ticket title.

@viralsampat
8 months ago

I have checked above mentioned issue and founds few files. Here, I have added its patch.

@viralsampat
8 months ago

I have checked above mentioned issue and founds few files. Here, I have added its patch.

#2 @SergeyBiryukov
8 months ago

  • Focuses docs added
  • Milestone changed from Awaiting Review to 6.5
  • Owner set to SergeyBiryukov
  • Status changed from new to reviewing

#3 @SergeyBiryukov
8 months ago

In 57190:

Docs: Document the $wpdb global in WP_User::__construct().

Follow-up to [19325].

Props upadalavipul.
See #60021.

#4 @SergeyBiryukov
8 months ago

In 57191:

Docs: Document the $link global in get_bookmark().

Follow-up to [8758].

Props upadalavipul, mukesh27.
See #60021.

#5 @SergeyBiryukov
8 months ago

In 57192:

General: Revert code changes from [57191].

The unit tests for get_bookmark() expect the function to modify the $GLOBALS array directly.

Follow-up to [57191].

See #60021.

#6 @SergeyBiryukov
8 months ago

In 57193:

Docs: Document the $current_screen global in _WP_Editors::editor().

Follow-up to [32899].

Props viralsampat.
See #60021.

#7 @SergeyBiryukov
8 months ago

In 57194:

Docs: Document the $wp_locale global in WP_Fatal_Error_Handler::handle().

Follow-up to [45277].

Props viralsampat.
See #60021.

#8 @SergeyBiryukov
8 months ago

In 57196:

Docs: Document some globals in wp-includes/deprecated.php.

Includes removing $allowed_options global references from functions where it's not actually used.

Props viralsampat.
See #60021.

#9 @SergeyBiryukov
8 months ago

In 57204:

Docs: Document the $shortcode_tags global in wp_just_in_time_script_localization().

Follow-up to [41395], [41844].

Props upadalavipul.
See #60021.

#10 @SergeyBiryukov
8 months ago

In 57216:

Docs: Document some globals in wp-includes/widgets.php.

Follow-up to [41555], [50995].

Props upadalavipul.
See #60021.

#11 @SergeyBiryukov
8 months ago

In 57223:

Docs: Remove unused $posts global reference in get_attachment_template().

Follow-up to [32628], [32804].

Props viralsampat.
See #60021.

#12 @SergeyBiryukov
8 months ago

In 57225:

Customize: Remove unused $wpdb global in _wp_customize_publish_changeset().

Follow-up to [38810], [39180], [41192], [41824].

Props viralsampat.
See #60021.

@shailu25
8 months ago

Added Since before global & added global before param in documentation as per php coding standard in src/wp-includes/admin-bar.php

#13 @SergeyBiryukov
8 months ago

In 57226:

Docs: Document the $wp_hasher global in wp_generate_user_request_key().

Includes adding a description for the global in a few other functions.

Follow-up to [42791], [42964], [43008].

Props viralsampat.
See #60021.

@viralsampat
7 months ago

I have checked above mentioned issue and founds few files. Here, I have added its patch.

#14 @SergeyBiryukov
7 months ago

In 57230:

Docs: Document the $post global in REST API posts and revisions controllers.

Follow-up to [38832], [40601].

Props viralsampat.
See #60021.

@viralsampat
7 months ago

I have checked above mentioned issue and founds few files. Here, I have added its patch.

@shailu25
7 months ago

I have Added Global Documentation in wp-includes/rss.php & wp-includes/widgets.php

#15 @SergeyBiryukov
7 months ago

In 57234:

Docs: Document the $wp_registered_sidebars global in wp_map_sidebars_widgets().

Follow-up to [41555].

Props shailu25.
See #60021.

@viralsampat
7 months ago

I have checked above mentioned issue and founds few files. Here, I have added its patch.

@shailu25
7 months ago

I have Added Global Documentation for Twenty Thirteen theme, Twenty Fourteen theme & Twenty Fifteen theme.

@shailu25
7 months ago

Added Global Documentations

#16 @shailu25
7 months ago

I have added global documentation in below files.

/wp-includes/blocks/block.php
/wp-includes/blocks/calendar.php
/wp-includes/blocks/comments.php

@viralsampat
7 months ago

I have checked above mentioned issue and founds few files. Here, I have added its patch.

#17 @sabernhardt
6 months ago

Some of the changes in these patches were probably skipped intentionally, but below is the status of each patch. It could help determine what still should be done toward 6.5 and what might belong on a separate ticket/issue.

60021.patch:
Completed in r57190 and r57191 (some changes from r57191 reverted in r57192).

60021.2.patch:
Mostly added in r57193, r57194, and r57196, but the $post global is not documented in wp-includes/feed-atom-comments.php or wp-includes/feed-rss2-comments.php.

60021.3.patch:
Proposes documenting $table_prefix global in wp-settings.php, in the same docblock as $wpdb.

60021.4.patch:
Completed in r57204 and r57216.

60021.5.patch:
Completed in r57223, r57225, and r57226.

60021.6.patch:
Proposes documenting $GLOBALS['_paused_plugins'] for three functions in wp-admin/includes/plugin.php:

  • is_plugin_paused()
  • wp_get_plugin_error()
  • paused_plugins_notice()

60021.diff:
Proposes reordering existing documentation in wp-includes/admin-bar.php. Grouping the two since lines together before global in wp_admin_bar_edit_site_menu() would follow up on r56209; moving $wp_customize global before the param in wp_admin_bar_customize_menu() would follow up on r38810.

60021.7.patch:
The getid3.lib.php change would need to be made upstream in that external library (earlier, I incorrectly said that getID3 was adopted). The two REST API files received $post documentation in r57230.

60021.8.patch:
Proposes documenting $GLOBALS['_paused_themes'] for three functions in wp-admin/includes/theme.php plus one in wp-includes/load.php:

  • is_theme_paused()
  • wp_get_theme_error()
  • paused_themes_notice()
  • wp_skip_paused_themes()

60021.9.patch:
Proposes documenting $wp_embed and $wp_plugin_paths in wp-settings.php as well as $GLOBALS['xmlrpc_logging'] in the deprecated function logIO() (xmlrpc.php).

60021.10.patch:
Proposes documenting $GLOBALS['_paused_plugins'] in wp_skip_paused_plugins() (in wp-includes/load.php).

60021.11.patch:
Completed in r57234 and r57370.

60021.12.patch:
Completed in r57193.

60021.13.patch:
Proposes documenting two variables in wp-settings.php that are in other patches ($GLOBALS['table_prefix'] in 60021.3.patch and $GLOBALS['wp_plugin_paths'] in 60021.9.patch).

60021.14.patch:
The $link global in bookmark.php is already documented in r57191 (as an object, not a string). The $xmlrpc_logging global documentation is also proposed in 60021.9.patch.

60021.15.patch:
Proposes documenting $wp_local_package and $wp_locale globals in wp-admin/setup-config.php the way they are in wp-admin/install.php. It also adds $table_prefix in wp-settings.php (compare with 60021.3.patch and 60021.13.patch).

60021.16.patch:
Proposes documenting the $_wp_tests_development_mode global within the wp_get_development_mode() docblock, though the variable has a comment about its use "exclusively for core tests."

60021.17.patch:
Bundled themes are on a separate ticket, #58715, and the pull request includes these items.

60021.18.patch and 60021.19.patch:
Changes need to be made upstream in the Gutenberg repository and then synced to files in the wp-includes/blocks directory.

Last edited 6 months ago by sabernhardt (previous) (diff)

#18 @sabernhardt
6 months ago

I corrected my mistake in the last comment (getID3 is still an external library).

Below is a chart of the remaining variables to consider adding to docblocks.

Variables Files Patches
$table_prefix wp-settings.php 60021.3.patch, 60021.13.patch, 60021.15.patch
$wp_embed wp-settings.php 60021.9.patch
$wp_plugin_paths wp-settings.php 60021.9.patch, 60021.13.patch
$xmlrpc_logging xmlrpc.php 60021.9.patch, 60021.14.patch
$wp_local_package and
$wp_locale
wp-admin/setup-config.php 60021.15.patch
$_paused_plugins wp-admin/includes/plugin.php and
wp-includes/load.php
60021.6.patch and 60021.10.patch (together)
$_paused_themes wp-admin/includes/theme.php and
wp-includes/load.php
60021.8.patch
$_wp_tests_development_mode wp-includes/load.php 60021.16.patch
$post wp-includes/feed-atom-comments.php and
wp-includes/feed-rss2-comments.php
60021.2.patch
reordering only (not adding a variable) wp-includes/admin-bar.php 60021.diff

#19 @swissspidy
5 months ago

Thanks for the table, very helpful!

@SergeyBiryukov did you want to commit those in time for RC? Otherwise probably best to just open a new ticket for 6.6 to address the rest.

#20 @SergeyBiryukov
5 months ago

In 57747:

Docs: Correct the placement of @global tags in wp-includes/admin-bar.php.

Follow-up to [38810], [56209].

Props shailu25, sabernhardt.
See #60021.

@sabernhardt
5 months ago

adds docblocks for $table_prefix, $wp_embed and $wp_plugin_paths

#21 @sabernhardt
5 months ago

I combined the three wp-settings.php changes into the same patch, adding @since tags.

  • $table_prefix, added in [18993]
  • $wp_embed, globalized in [18532] and moved to wp-settings.php in [38362]
  • $wp_plugin_paths, added in [27158]

Props: upadalavipul and viralsampat.

#22 @SergeyBiryukov
5 months ago

In 57748:

Docs: Document some globals in wp-settings.php.

Follow-up to [18532], [18993], [27158], [38362].

Props upadalavipul, viralsampat, sabernhardt.
See #60021.

#23 @sabernhardt
5 months ago

I also checked history for xmlrpc.php and setup-config.php.

xmlrpc.php

  • When [19935] deprecated both the logIO() function and $xmlrpc_logging 12 years ago, it specifically removed documentation for the global.
  • If it is still worth adding a @global tag within the logIO() docblock, the variable accepted multiple types: int|bool (either 0, 1 or their boolean equivalents).
  • For a possible @since tag, [1348] had added the variable (and the rest of the file) the day after a version bump in [1344]. This suggests the next version was 1.5.0, but I found it in the zipped packages for both 1.0-platinum and 1.2-mingus.

setup-config.php

  • [51477] removed @global tags from the setup_config_display_header() docblock, where they did not belong. However, it did not put a docblock closer to those globals, as it is in install.php (and in the setup-config.php part of 60021.15.patch).
  • [32642] added the documentation for $wp_local_package and $wp_locale in install.php, and then [45737] and [47230] included the descriptions.
  • [29669] added the $wp_locale variable to setup-config.php, and [29705] added $wp_local_package.
Last edited 5 months ago by sabernhardt (previous) (diff)

#24 @swissspidy
5 months ago

  • Type changed from defect (bug) to task (blessed)

#25 @SergeyBiryukov
5 months ago

In 57752:

Docs: Document the $xmlrpc_logging global in logIO().

Follow-up to [1348], [19935].

Props viralsampat, upadalavipul, sabernhardt.
See #60021.

#26 @SergeyBiryukov
5 months ago

In 57756:

Docs: Document some globals in wp-admin/setup-config.php.

Follow-up to [29669], [29705], [32642], [45737], [47230], [51477].

Props upadalavipul, sabernhardt.
See #60021.

#27 @sabernhardt
5 months ago

History for the remaining globals:

  • [44973] added $_paused_plugins and $_paused_themes (these variable names would start with $_)
  • [56042] added $_wp_tests_development_mode
  • [18716] added $post added to comments feed loops

#28 @SergeyBiryukov
5 months ago

In 57759:

Docs: Document the $post global in comment feed templates.

Follow-up to [18716].

Props viralsampat, sabernhardt.
See #60021.

#29 @SergeyBiryukov
5 months ago

In 57772:

Docs: Document the usage of $_paused_plugins and $_paused_themes globals.

Follow-up to [44973].

Props upadalavipul, sabernhardt.
See #60021.

#30 @SergeyBiryukov
5 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

Thanks everyone! I think we're done here, let's create a new ticket for any remaining issues.

#31 @SergeyBiryukov
5 months ago

In 57773:

Coding Standards: Remove some extra trailing spaces.

Follow-up to [57772].

See #60021.

@viralsampat
5 months ago

I have checked above mentioned issue and founds few files. Here, I have added its patch.

@viralsampat
5 months ago

I have checked above mentioned issue and founds few files. Here, I have added its patch.

@viralsampat
4 months ago

I have worked on above mentioned issue and removed unused global variable from wp-includes.

#32 @SergeyBiryukov
4 months ago

In 57898:

Networks and Sites: Remove unused $wpdb global in update_blog_details().

Follow-up to [43548].

Props viralsampat.
See #60021.

Note: See TracTickets for help on using tickets.