WordPress.org

Make WordPress Core

Opened 2 years ago

Closed 2 years ago

#34858 closed defect (bug) (fixed)

Improve documentation for request_filesystem_credentials()

Reported by: swissspidy Owned by: swissspidy
Milestone: 4.5 Priority: normal
Severity: normal Version:
Component: Filesystem API Keywords: good-first-bug has-patch commit
Focuses: docs Cc:

Description

As per the @todo comment in request_filesystem_credentials(), the function's docblock could be improved a lot.

The params are not aligned correctly and, punctuation could be improved and proper descriptions for the optional params are needed.

See the PHP documentation standards for more details.

Attachments (3)

#34858-request-filesystem-credentials.diff (1.1 KB) - added by slushman 2 years ago.
Add better documentation to DocBlock for request-filesystem-credentials().
34858.diff (1.7 KB) - added by danhgilmore 2 years ago.
Updated the docblock
34858.2.diff (3.7 KB) - added by swissspidy 2 years ago.

Download all attachments as: .zip

Change History (10)

@slushman
2 years ago

Add better documentation to DocBlock for request-filesystem-credentials().

#1 @slushman
2 years ago

  • Keywords has-patch added; needs-patch removed

#2 @swissspidy
2 years ago

  • Keywords needs-patch added; has-patch removed

@slushman Thanks for the patch!

Please note that I created this ticket specifically for the function request_filesystem_credentials(), not the WP_Upgrader_Skin::request_filesystem_credentials() method. (Of course that one needs some docs love too, but I'd rather do that in a separate ticket and for the whole class.)

Would you mind creating a new patch for request_filesystem_credentials() in wp-admin/includes/file.php? You can probably re-use some of the text used in the request_filesystem_credentials filter docs.

@danhgilmore
2 years ago

Updated the docblock

#3 @danhgilmore
2 years ago

  • Keywords has-patch added; needs-patch removed

#4 @DrewAPicture
2 years ago

  • Owner set to swissspidy
  • Status changed from new to reviewing

@swissspidy
2 years ago

#5 @swissspidy
2 years ago

  • Milestone changed from Awaiting Review to 4.5

I updated the patch again in 34858.2.diff to add default params and fix alignment of both the function and the filter DocBlocks.

#6 @swissspidy
2 years ago

  • Keywords commit added

#7 @SergeyBiryukov
2 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 35888:

Docs: Improve documentation for request_filesystem_credentials() and the corresponding filter.

Props swissspidy, danhgilmore, slushman.
Fixes #34858.

Note: See TracTickets for help on using tickets.