There is no comment for the initialize function

[yagniksangani]

Hello, there is a comment missing for the initialize function in file wp-includes/class-wp-admin-bar.php

[yagniksangani]

Also there is comment missing for the add_menus function on same file

[audrasjb]

Hello @yagniksangani, thanks for the ticket!

Indeed. Would you like to create a patch for this?

[yagniksangani]

Yes, I would like to create a patch for this.
Replying to audrasjb:

Hello @yagniksangani, thanks for the ticket!

Indeed. Would you like to create a patch for this?

[yagniksangani]

Hello @audrasjb
Now, what do I need to do for this ticket, can you please guide me? As I'm new to core contribution.

[hellofromTonya]

Replying to yagniksangani:

Now, what do I need to do for this ticket, can you please guide me? As I'm new to core contribution.

Hello @yagniksangani, Here are a couple of resources to help you get started creating and submitting a patch:

• ​Creating a patch with the command line (as I noticed in the pngs you're using git)
• ​FAQ for New Contributors

For creating the patch, you're very close with the pngs you uploaded.

• Checkout the master branch (the images show you are on the 5.8 branch)
• Sync your copy of master to the upstream wordpress/wordpress-develop repo, i.e. by pulling the latest changes from upstream and then merging these changes into your local copy
• Add the comment change
• Then svn diff > 54191.diff to create the patch file
• Then upload that patch file to this ticket

[yagniksangani]

Patch

[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.

​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
/**
 * Set up the hooks for the [thing].
 *
 * @since X.X.X
 */

and

<?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 ​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?

[audrasjb]

Thanks for the patch!

Aside from Tonya’s comments, I'd add another thing to note: it's better to generate the diff file in the wordpress-develop folder because that's easier for other people to apply your patch on their side. On this particular patch, that's not an issue but it can make things harder to test for future ones :-)

(so in your case, the path of the file will be src/wp-includes/class-wp-admin-bar.php rather than wp-includes/class-wp-admin-bar.php)

[yagniksangani]

New Diff File

[sabernhardt]

The updated patch looks good.

We could also consider adding a DocBlock for the public render function (not the protected _render).

[mukesh27]

If we don't have doc block description for render then we can add @since version number.

[yagniksangani]

New Diff File

[rehanali]

I have added the comments for the initializing function

[rehanali]

New file added

[audrasjb]

@rehanali please do not change the ticket properties when it's not needed

It's not a feature request, it's not an UI ticket, it's not invalid, and it's not an Administration ticket.

[SergeyBiryukov]

In 51876:

Docs: Improve documentation for WP_Admin_Bar methods.

Add some missing descriptions and @since tags.

Follow-up to [15671], [19120], [19429], [19501], [19558], [25475], [25478], [25563], [32534], [35157], [40947], [45821], [48826].

Props yagniksangani, hellofromTonya, audrasjb, sabernhardt, mukesh27, rehanali, SergeyBiryukov.
Fixes #54191.