WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#28408 closed defect (bug) (fixed)

Improve phpdocs for wp-includes/media.php

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: 4.2 Priority: normal
Severity: normal Version:
Component: Media Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description (last modified by mikeschroder)

Bring docs in wp-admin/includes/media.php up to Core Docs Syntax standards.

Somewhat related to #27882

Attachments (2)

28408.patch (19.2 KB) - added by stevegrunwell 5 years ago.
Clean up DocBlock formatting, add some missing arguments, global declarations, and @since tags.
28408.2.patch (35.5 KB) - added by DrewAPicture 5 years ago.

Download all attachments as: .zip

Change History (9)

#1 @DrewAPicture
5 years ago

In 28632:

Remove unnecessary "not used" notation for filter parameters in wp-admin/includes/media.php.

Also add @param and @return descriptions.

See #28408.

#2 @DrewAPicture
5 years ago

  • Description modified (diff)

#3 @mikeschroder
5 years ago

  • Description modified (diff)
  • Milestone changed from 4.0 to Future Release
  • Owner set to DrewAPicture
  • Status changed from new to assigned

@stevegrunwell
5 years ago

Clean up DocBlock formatting, add some missing arguments, global declarations, and @since tags.

#4 @DrewAPicture
5 years ago

  • Keywords needs-patch added

Hi Steve, thanks for the patch. Here are some general notes on 28408.patch:

  • There should be a blank line between the @since tag block (one or more) and any other tags, such as @see. Also, @since is always first.
  • We have a very specific syntax for marking parameters as optional (the code reference expects it):
    @param type $var Optional. Description. Accepts. Default.
    
  • There are several parameters you've fixed descriptions for that are also optional so they should be marked as such, see above for that syntax

#5 @DrewAPicture
5 years ago

  • Keywords has-patch added; needs-patch removed
  • Milestone changed from Future Release to 4.2
  • Status changed from assigned to reviewing

#6 @DrewAPicture
5 years ago

  • Summary changed from Improve phpdocs for wp-admin/includes/media.php to Improve phpdocs for wp-includes/media.php

#7 @DrewAPicture
5 years ago

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

In 31530:

Clarify a wide variety of function, parameter, and return descriptions in DocBlocks throughout wp-includes/media.php.

Props stevegrunwell, DrewAPicture.
Fixes #28408.

Note: See TracTickets for help on using tickets.