Docs: Standardise the description for image size parameters

[johnbillion]

Many functions and hooks in WordPress provide a parameter which accepts an image size value, which can almost always be a registered image size name or an array of width/height dimensions. The documentation for these parameters is inconsistent which makes the accepted values confusing to developers.

Let's standardise the description of any parameter which accepts an image size.

Relevant Functions

• _load_image_to_edit_path()
• _wp_get_image_size_from_meta()
• adjacent_image_link()
• get_the_post_thumbnail()
• image_add_caption() (parameter isn't used)
• image_constrain_size_for_editor()
• image_downsize()
• image_get_intermediate_size()
• load_image_to_edit()
• next_image_link()
• previous_image_link()
• the_post_thumbnail()
• wp_calculate_image_sizes()
• wp_get_attachment_image_sizes()
• wp_get_attachment_image_src()
• wp_get_attachment_image_srcset()
• wp_get_attachment_image_url()
• wp_get_attachment_image()
• wp_get_attachment_link()

The following functions only accept a registered image size name, not an array of width/height dimensions:

• _wp_get_image_size_from_meta()
• gallery_shortcode() ($attr['size'] parameter) because the value gets passed to sanitize_html_class()
• get_image_send_to_editor() because the value gets passed to get_image_tag()
• get_image_tag() because the value gets directly used as an HTML attribute

Relevant Hooks

• {$adjacent}_image_link
• admin_post_thumbnail_size
• begin_fetch_post_thumbnail_html
• editor_max_image_size
• end_fetch_post_thumbnail_html
• get_the_post_thumbnail_url
• image_downsize
• image_get_intermediate_size
• load_image_to_edit_attachmenturl
• load_image_to_edit_filesystempath
• load_image_to_edit_path
• load_image_to_edit
• post_thumbnail_html
• post_thumbnail_size
• the_post_thumbnail_url
• wp_calculate_image_sizes
• wp_get_attachment_image_attributes
• wp_get_attachment_image_src
• wp_get_attachment_link

The following hooks won't pass an array of width/height dimensions because the value comes from get_image_tag():

• get_image_tag_class
• get_image_tag
• image_send_to_editor

Accepted Values

The following values are accepted by all parameters that accept an image size (except the exceptions noted above):

• full
• large
• medium
• medium_large
• thumbnail
• Any custom registered image size name
• An array of width/height dimensions

In addition there is a post-thumbnail image size referenced in a few places but its source and usage is not clear, I haven't looked into it yet.

[dilipbheda]

Changed few functions description.

[joemcgill]

Thanks for the suggestion @johnbillion and for going through all of these functions/hooks. For clarification, are you suggesting that only the docs need to be updated to be more accurate here, or that we need to adjust the actual function signatures in order to bring more consistency to these functions overall?

[SergeyBiryukov]

Crossposting a comment by @marekdedic from comment:71:ticket:48303:

Hi, I started by looking at the function get_the_post_thumbnail and its parameter $size, which is currently of the type string|array. I think this could be narrowed down to string|int[] by examining its source and all the functions and hooks it calls. As such, I think these functions and hooks could have their parameter $size narrowed in the same way. The ones I encountered:

Functions:

• get_the_post_thumbnail
• wp_get_attachment_image
• wp_get_attachment_image_src
• image_downsize
• image_get_intermediate_size
• image_constrain_size_for_editor

Hooks:

• begin_fetch_post_thumbnail_html
• end_fetch_post_thumbnail_html
• wp_get_attachment_image_src
• image_downsize
• image_get_intermediate_size
• editor_max_image_size

However, I'm pretty sure there are more.

[johnbillion]

In 49016:

Media: Correct some types in docblocks for filters related to thumbnails.

Props dilipbheda

See #47364, #50768

[johnbillion]

In 49017:

Media: Correct some types for attachment ID parameters passed to functions and filters.

See #47364, #50768

[johnbillion]

In 49020:

Docs: Inline documentation improvements for media related functions and hooks.

See #47364, #50768

[johnbillion]

In 49021:

Media: Standardise the description for image size parameters.

This brings continuity to all the image related functions and filters which accept or pass a size parameter.

Props dilipbheda, johnbillion

Fixes #47364