WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 4 years ago

#34733 closed defect (bug) (fixed)

Responsive Images: Inline docs fixes

Reported by: joemcgill Owned by: joemcgill
Milestone: 4.5 Priority: normal
Severity: normal Version: 4.4
Component: Media Keywords: has-patch ongoing
Focuses: docs Cc:
PR Number:

Description

While preparing an updated version of the RICG Responsive Images Plugin, we came across a few places where the inline docs could be improved or were inaccurate.

Attachments (3)

34733.diff (3.2 KB) - added by joemcgill 4 years ago.
34733.1.diff (1.8 KB) - added by jaspermdegroot 4 years ago.
Update see tags in responsive images functions DocBlocks
34733.2.diff (1.3 KB) - added by joemcgill 4 years ago.
Remove redundant 'type' indicators from docblocs

Download all attachments as: .zip

Change History (18)

@joemcgill
4 years ago

#1 @mikeschroder
4 years ago

  • Component changed from General to Media

+1

Chatted with @DrewAPicture -- let's use this ticket for tracking of any other docs fixes that might come up for RespImg pre 4.4 as well, to keep them in one place.

#2 @joemcgill
4 years ago

Sounds good to me.

#3 @joemcgill
4 years ago

  • Owner set to joemcgill
  • Status changed from new to accepted

#4 @DrewAPicture
4 years ago

In 35696:

Docs: Clarify some parameter and return descriptions in the DocBlocks for wp_get_attachment_image_srcset() and wp_calculate_image_srcset(), wp_get_attachment_image_sizes(), and the wp_calculate_image_srcset filter.

Props joemcgill.
See #34733.

#5 @DrewAPicture
4 years ago

  • Keywords has-patch removed

@jaspermdegroot
4 years ago

Update see tags in responsive images functions DocBlocks

#6 @jaspermdegroot
4 years ago

Following [35696], in 34733.1.diff:

Updated the @see tags of the responsive images functions:

  • Removed the quotes from the function names
  • Changed the functions we refer to in the DocBlock of wp_image_add_srcset_and_sizes() to the ones we actually call inside that function
  • Refer to wp_calculate_image_srcset() in the wp_get_attachment_image_srcset() DocBlock because it heavily relies on it
  • Refer to wp_calculate_image_sizes() in the wp_get_attachment_image_sizes() DocBlock because it heavily relies on it
Last edited 4 years ago by SergeyBiryukov (previous) (diff)

#7 follow-up: @joemcgill
4 years ago

@DrewAPicture: Some clarification if we're _doing_it_wrong() with @see tags would be helpful here. Jasper and I were a bit confused by the Docs Handbook. Thanks.

#8 @joemcgill
4 years ago

34733.2.diff removes some redundant 'type' strings from the wp_calculate_image_srcset filter docblock. This issue was originally caught by @DH-Shredder in 34736.3.patch.

@joemcgill
4 years ago

Remove redundant 'type' indicators from docblocs

This ticket was mentioned in Slack in #core by wonderboymusic. View the logs.


4 years ago

#10 in reply to: ↑ 7 @DrewAPicture
4 years ago

  • Keywords has-patch added

Replying to joemcgill:

@DrewAPicture: Some clarification if we're _doing_it_wrong() with @see tags would be helpful here. Jasper and I were a bit confused by the Docs Handbook. Thanks.

What did you find confusing? 34733.1.diff looks fine to me.

#11 @SergeyBiryukov
4 years ago

In 35715:

Docs: Add @see tags for wp_get_attachment_image_srcset() and wp_get_attachment_image_sizes().

Update @see tags for wp_make_content_images_responsive() and wp_image_add_srcset_and_sizes().

Props jaspermdegroot.
See #34733.

#12 @SergeyBiryukov
4 years ago

In 35716:

Docs: Remove redundant type strings from the wp_calculate_image_srcset filter DocBlock.

Props DH-Shredder, joemcgill.
See #34733.

#13 @wonderboymusic
4 years ago

  • Keywords ongoing added
  • Milestone changed from 4.4 to Future Release

we all know this is a brand new feature that might need commits for docs - moving off the report until motion picks up again

#14 @jaspermdegroot
4 years ago

  • Keywords close added

I think the inline docs for the responsive images functions are in good shape now so we can close this ticket. Can always open new tickets for specific issues.

#15 @DrewAPicture
4 years ago

  • Keywords close removed
  • Milestone changed from Future Release to 4.5
  • Resolution set to fixed
  • Status changed from accepted to closed
Note: See TracTickets for help on using tickets.