Responsive Images: Inline docs fixes

[joemcgill]

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.

[kirasong]

+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.

[joemcgill]

Sounds good to me.

[DrewAPicture]

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.

[jaspermdegroot]

Update see tags in responsive images functions DocBlocks

[jaspermdegroot]

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

[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.

[joemcgill]

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]

Remove redundant 'type' indicators from docblocs

[DrewAPicture]

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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

In 35716:

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

Props DH-Shredder, joemcgill.
See #34733.

[wonderboymusic]

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

[jaspermdegroot]

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.