Improve `wp_get_attachment_image()` and `wp_get_attachment_image_attributes` docs.

[juanfra]

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?

[DrewAPicture]

Hi @juanfra: I think the inline documentation for return values could benefit from specifying exactly which attributes you'll get and in which circumstances. Would you like to submit a patch?

[juanfra]

Hi @DrewAPicture!

Thanks for your time.

Yeah totally agree. Do you think by documenting the return values of the function is enough to not specify the default params($atts) for the wp_get_attachment_image_attributes filter? I think if we include them as well, we won't cause any harm and it could help someone out there trying to learn or implement something cool with images.

[Mte90]

draft for doc on wp_get_attachment_image_attributes

[Mte90]

My idea for the docs, or in case we need to explain every value but I don't think that is the best thing.

[peterwilsoncc]

Moving to the 5.1 milestone due to the WordPress 5.0 focus on the new
editor (Gutenberg).

[joemcgill]

The current patch is an improvement, but I'd prefer to see the whole array documented per ​our documentation in the handbook.

[desrosj]

This needs a patch refresh per the latest comment above.

[desrosj]

Since this still needs an updated patch and 5.2 beta is in less than 2 days, I am going to punt this. @antpb if you have a new patch and feel it is ready in time, feel free to move back.

[kirasong]

@antpb Are you planning on doing any more work here this release?

I'm noticing this ticket is marked an enhancement, but docs changes can land at any time.

If you have time this release for review, would love to see it land (whether now or during beta), but we'll need to either reclassify it, or move it out of the milestone for triage purposes.

[davidbaumwald]

Although doc changes can be made between beta 1 and RC, there are 200 bug tickets still to triage. With 5.3 Beta 1 landing in a couple of hours, this is being moved for consideration in 5.4 If a committer feels this change should be made before RC, they can move it back and commit.

[davidbaumwald]

@antpb Is this still in the cards for 5.4?

[davidbaumwald]

Similar to its position in 5.3, this still needs a refresh. Although doc changes can be made between beta 1 and RC, there are ~175 bug tickets still to triage. With 5.4 Beta 1 landing in a couple of hours, this is being moved for consideration in 5.4 If a committer feels this change should be made before RC, they can move it back and commit.

[SergeyBiryukov]

In 47249:

Docs: Improve documentation for the $attr parameter of wp_get_attachment_image().

Props juanfra, Mte90, DrewAPicture, joemcgill, SergeyBiryukov.
Fixes #36661.