WordPress.org

Make WordPress Core

Opened 2 years ago

Last modified 2 years ago

#41491 new defect (bug)

Add a DocBlock for WP_Comments_List_Table::floated_admin_avatar()

Reported by: akbarhusen Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: Comments Keywords: needs-patch
Focuses: docs Cc:
PR Number:

Description (last modified by swissspidy)

The WP_Comments_List_Table has lots of properties and methods that lack proper inline documentation.

These should be updated according to the PHP documentation standards that can be found at https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/.

Attachments (2)

41491.patch (631 bytes) - added by akbarhusen 2 years ago.
41491.1.patch (762 bytes) - added by ajayghaghretiya1 2 years ago.

Download all attachments as: .zip

Change History (11)

@akbarhusen
2 years ago

#1 @akbarhusen
2 years ago

i have attach the patch.

#2 @ayeshrajans
2 years ago

Hi @akbarhusen - The patch refers to a @global variable that is not global, but only a function argument.

The parameter type is wrong as well.
It should be, @param string $name and @param int $comment_ID. The return type could be more meaningful too.

Also, I believe others will agree too, that one ticket to handle all the documentation issues in this class will help others to maintain it easily, instead of several small ones with vague titles.

Thanks.

#3 @Soean
2 years ago

Hello @akbarhusen
the access public annotations have been removed from the DocBlocks - see #41452 and handbook (https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-functions-class-methods)

#4 @Soean
2 years ago

  • Component changed from General to Comments
  • Focuses docs added
  • Keywords needs-refresh added
  • Summary changed from document needs improvements to Documentation needs improvements

#5 @swissspidy
2 years ago

  • Description modified (diff)
  • Keywords needs-patch added; needs-refresh removed
  • Summary changed from Documentation needs improvements to WP_Comments_List_Table documentation improvements

In addition to that, please try to write more meaningful ticket titles than "Documentation needs improvement" and write at least a short description.

It's hard for us to garden tickets on trac when there are dozens of tickets with the same title and no description.

#6 @ayeshrajans
2 years ago

Couldn't agree more with @swissspidy. I guess these recent tickets are coming from a WordCamp or such event sprint. There are several of them I noticed recently.

#7 @ajayghaghretiya1
2 years ago

  • Keywords has-patch added; needs-patch removed

#8 @netweb
2 years ago

  • Keywords needs-patch added; has-patch removed

Please read the feedback already added to this ticket please

  • It is also deleting a blank line above the function comment when it should not

When updating the patch and adding it to the ticket here please explain the changes in the patch you have just uploaded and how it differs from any previous patch uploaded please :)

Last edited 2 years ago by netweb (previous) (diff)

#9 @SergeyBiryukov
2 years ago

  • Summary changed from WP_Comments_List_Table documentation improvements to Add a DocBlock for WP_Comments_List_Table::floated_admin_avatar()
Note: See TracTickets for help on using tickets.