Responsive Images: Make new function/filter signatures more consistent

[joemcgill]

As a part of the responsive images features being added in 4.4, we should promote internal consistency in the new functions and filters we're adding. To that end, several of us working on this feature have discussed splitting wp_get_attachment_image_sizes() into two functions: an internally used function that calculates the sizes attribute, and an external use function that can be used easily in themes. This mimics the pattern we already established with wp_calculate_image_srcset() and wp_get_attachment_image_srceset().

[joemcgill]

34612.diff​ moves the logic of wp_get_attachment_image_sizes() to wp_calculate_image_sizes() and renames the filter wp_calculate_image_sizes(). The parameter order now matches the order or params in wp_calculate_image_srcset().

The previous function name: wp_get_attachment_image_sizes() now accepts an attachment id and optional size parameter, which matches the signature of wp_get_attachment_image_srcset() and is consistent with the other wp_get_attachment_image_ template functions.

Tests and docs have been updated.

[azaozz]

In 35569:

Responsive images: make the new functions and filters signatures more consistent.

Props joemcgill.
Fixes #34612.

[joemcgill]

Update params for wp_calculate_image_srcset filter.

[joemcgill]

Looks like I missed updating the params for wp_calculate_image_srcset filter in 34612.diff​. I've uploaded 34612.filter.diff​, which corrects the param order and adds $image_src to the filter. Inline docs are updated as well.

[kirasong]

34612.filter.diff​ looks good; thanks!

[DrewAPicture]

Replying to joemcgill:

Looks like I missed updating the params for wp_calculate_image_srcset filter in 34612.diff​. I've uploaded 34612.filter.diff​, which corrects the param order and adds $image_src to the filter. Inline docs are updated as well.

We're going to have to move the code example into the hook doc description. As-is, it would be read as a sentence with the extra spaces removed. So let's move it to the description, four-space indented and figure out a good way to refer back to it from the parameter description.

[joemcgill]

After discussion with @DrewAPicture, in 34612.filter.2.diff​ I've changed the inline docs to use proper @type docs for the array of sources being passed in the wp_calculate_image_srcset filter, per the ​inline docs handbook.

[azaozz]

In 35591:

Responsive images: properly arrange the parameters for the wp_calculate_image_srcset filter and add fix the inline documentation.

Props joemcgill.
Fixes #34612.

[DrewAPicture]

In 35592:

Docs: Fix some formatting in the hook doc for the wp_calculate_image_srcset filter and clarify the summary.

See #34612.

[kraftbj]

Minor: Remove blank line from inline docs.

[kraftbj]

.2 without the extra stuff :) -- removing blank line.

[kraftbj]

@DrewAPicture Super minor, but there's a blank line in the inline docs L1092. Removed in .2.diff.

[DrewAPicture]

In 35601:

Docs: Remove an empty line from the hook doc for the wp_calculate_image_srcset filter, introduced in [35592].

Props kraftbj.
See #34612.

[joemcgill]

I noticed that we had marked several params in wp_calcuate_image_sizes() as optional, but had not defined default values. 34612.4.diff​ corrects this issue and includes a few other fixes to the docblocs for this function and filter.

[DrewAPicture]

In 35672:

Docs: Properly mark optional parameters as such in the DocBlock and function signature for wp_calculate_image_sizes().

Also updates the subsequent hook docs for the wp_calculate_image_sizes filter.

Props joemcgill.
Fixes #34612.