Opened 8 years ago
Closed 5 years ago
#41491 closed defect (bug) (fixed)
Add a DocBlock for WP_Comments_List_Table::floated_admin_avatar()
Reported by: |
|
Owned by: |
|
---|---|---|---|
Milestone: | 5.5 | Priority: | normal |
Severity: | normal | Version: | |
Component: | Comments | Keywords: | needs-patch |
Focuses: | docs | Cc: |
Description (last modified by )
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)
Change History (13)
#2
@
8 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
@
8 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
@
8 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
@
8 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
@
8 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.
#8
@
8 years ago
- Keywords needs-patch added; has-patch removed
Please read the feedback already added to this ticket please
- As noted in https://core.trac.wordpress.org/ticket/41491#comment:3
@access public
has been removed from core, patches should no longer contain these.
- The patch is also missing the
@since
revision, see https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#since-section-changelogs
- 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 :)
#9
@
8 years ago
- Summary changed from WP_Comments_List_Table documentation improvements to Add a DocBlock for WP_Comments_List_Table::floated_admin_avatar()
i have attach the patch.