[wp-trac] [WordPress Trac] #54191: There is no comment for the initialize function

[WordPress Trac]

#54191: There is no comment for the initialize function
---------------------------+-------------------------------
 Reporter:  yagniksangani  |       Owner:  (none)
     Type:  enhancement    |      Status:  reopened
 Priority:  normal         |   Milestone:  Awaiting Review
Component:  Toolbar        |     Version:
 Severity:  normal         |  Resolution:
 Keywords:  needs-patch    |     Focuses:  coding-standards
---------------------------+-------------------------------

Comment (by hellofromTonya):

 Thank you @yagniksangani for your patch! w00t!

 I'd like to offer you some feedback to further improve the method
 DocBlocks.

 The start of the DocBlock is a summary that describes "what" the
 function/method does. It should be clear, simple, and brief. It's purpose
 (the reason it exists) is to introduce the function/method in such a way
 that it ''tells folks what behavior it will do when calling/invoking
 it''****. Functions and methods do work. Start with a verb such as `Sets
 up`, `Initializes`, `Adds`, `Removes`, etc.

 [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php/ Here's the handbook page] for more
 information.

 I often find inspiration by exploring like named functions/methods within
 the codebase. In searching the codebase, there's only one other named
 `initialize`, but other initializers are called `init`. (Tip: Search
 `function init`.) A couple of common pattern are:

 {{{#!php
 <?php
 /**
  * Set up the hooks for the [thing].
  *
  * @since X.X.X
  */
 }}}

 and

 {{{#!php
 <?php
 /**
  * Initialize the [thing].
  *
  * @since X.X.X
  */
 }}}

 For this particular `initialize()` method, it's doing both: setting up the
 hooks and initializing the admin bar.

 What `@since`?
 This is the version number when the method was introduced.

 How can you discover which version number?
 There are a few techniques:

 - Look at the class' version number. Then go to the branch to determine if
 this method was first introduced with the class. Results: Yes it was
 [https://github.com/WordPress/wordpress-develop/blob/3.1/wp-includes
 /class-wp-admin-bar.php found here].
 - Use Trac blame feature, though this method is not as straightforward for
 finding what version introduced the code. It's great for finding the
 changeset and history of changesets.

 For the `initialize()` method, maybe something like:

 {{{
 /**
  * Initializes the admin bar.
  *
  * @since 3.1.0
  */
 }}}

 Want to give this a try for improving both methods?

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