[wp-trac] [WordPress Trac] #47364: Docs: Standardise the description for image size parameters

[WordPress Trac]

#47364: Docs: Standardise the description for image size parameters
-------------------------+-----------------------------
 Reporter:  johnbillion  |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  Media        |    Version:
 Severity:  normal       |   Keywords:  needs-patch
  Focuses:  docs         |
-------------------------+-----------------------------
 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.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/47364>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform