[wp-trac] [WordPress Trac] #51439: Docs: Undocumented @global instances

[WordPress Trac]

#51439: Docs: Undocumented @global instances
--------------------------+-------------------------------------
 Reporter:  ravipatel     |       Owner:  (none)
     Type:  defect (bug)  |      Status:  new
 Priority:  low           |   Milestone:  6.0
Component:  General       |     Version:  4.2
 Severity:  normal        |  Resolution:
 Keywords:  has-patch     |     Focuses:  docs, coding-standards
--------------------------+-------------------------------------
Changes (by SergeyBiryukov):

 * keywords:  has-patch needs-refresh close => has-patch
 * milestone:  Awaiting Review => 6.0


Comment:

 Hi there, thanks for the patches!

 I have checked the suggested changes and I agree with comment:4 that they
 don't seem to be necessary. These globals are not declared or documented
 in these particular places because they are all declared and documented
 elsewhere.

 For example, [45233] / #46602 removed the `$wpdb` declaration from `wp-
 admin/install.php`, because the variable is already available there, it
 was previously declared in `wp-load.php`. As noted in
 comment:2:ticket:46602:
 > Per the [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php/ documentation standards], the `@global` tag
 is meant to list PHP globals used within functions or methods.
 >
 > Looking at other files in `wp-admin`, it seems like we don't generally
 document `$wpdb` in code that itself is in the global namespace. The
 standards don't say anything about it either.

 The same goes for other variables in the patch too, they may not be
 explicitly declared in these specific instances but they are defined. If a
 static analysis tool flags them as undefined, that would be a false
 positive.

 On second thought, if the goal here is to improve developer experience, I
 guess there might be some benefit in declaring these globals explicitly. I
 think they should be declared closer to where they are used, so that the
 context is immediately clear, and there is no need to redefine them. See
 [attachment:"51439.diff"], moving to 6.0 for consideration.

 As for adding the `@var` keyword in `wp-admin/credits.php` and `wp-
 admin/includes/ajax-actions.php`: WordPress generally documents class
 properties or constants like that, but not local variables, so I don't
 think this is needed.

 As for declaring the `$wp_version` global in `wp-admin/includes/class-
 core-upgrader.php`: the current code specifically imports it as a local
 variable (we do that in a few other places as well), so I think there is
 no need to declare it as a global. Doing that might have unintended side
 effects, like changing the global value instead of the local one.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/51439#comment:7>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform