[wp-trac] [WordPress Trac] #36661: Improve `wp_get_attachment_image()` and `wp_get_attachment_image_attributes` docs.

[WordPress Trac]

#36661: Improve `wp_get_attachment_image()` and
`wp_get_attachment_image_attributes` docs.
-------------------------+-----------------------------
 Reporter:  juanfra      |      Owner:
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  General      |    Version:  4.5
 Severity:  normal       |   Keywords:
  Focuses:  docs         |
-------------------------+-----------------------------
 Hey there,

 While looking for a solution for another ticket I've seen that there's not
 much documentation for `wp_get_attachment_image()`, specifically for the
 string|array of the `$atts` parameter. I know, that you can get through
 the code and see that some of them are automatically generated (src,
 class, alt, srcset, sizes) and that you override them and at the same time
 you can define an unlimited amount of `$atts`, but perhaps there's other
 people trying to use the function and they do not know that. We might end
 up seeing ugly implementations of people trying to add data attributes to
 images, etc. This function is not documented in the codex, only in the
 Code Reference site.

 I think the most important part to explain is the `scrset` attribute as
 many people usually tries to use this type of function to deliver
 different images depending on the device in which the site is seen (Also,
 this is kind of covered by core in some ways now, but it is poorly
 documented). Or that you can add classes for retina support.

 The same is happening with the `wp_get_attachment_image_attributes` filter
 within that function. It is not listing the list of attributes that you
 get by default.

 I consider it is worth it to modify the phpdoc (at least) in the hook
 description, but I'm not sure if the phpdoc should be modified for the
 function. That's why I wanted to have some feedback before sending a
 patch.

 What do you think? Shall we add docs within the code or we should we leave
 notes on the code reference site?

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