Make WordPress Core

Opened 2 years ago

Last modified 3 weeks ago

#36661 new enhancement

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

Reported by: juanfra Owned by:
Milestone: 5.0 Priority: normal
Severity: minor Version: 4.4
Component: Media Keywords: has-patch dev-feedback
Focuses: docs Cc:


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?

Attachments (1)

36661.diff (668 bytes) - added by Mte90 15 months ago.
draft for doc on wp_get_attachment_image_attributes

Download all attachments as: .zip

Change History (8)

#1 @DrewAPicture
23 months ago

  • Keywords needs-patch added
  • Version changed from 4.5 to 4.4

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?

#2 @DrewAPicture
23 months ago

  • Component changed from General to Media

#3 @juanfra
23 months ago

  • Severity changed from normal to minor

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.

Last edited 23 months ago by juanfra (previous) (diff)

This ticket was mentioned in Slack in #docs by morganestes. View the logs.

18 months ago

15 months ago

draft for doc on wp_get_attachment_image_attributes

#5 @Mte90
15 months ago

  • Keywords has-patch dev-feedback added; needs-patch removed

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

This ticket was mentioned in Slack in #core by mte90. View the logs.

3 weeks ago

#7 @SergeyBiryukov
3 weeks ago

  • Milestone changed from Awaiting Review to 5.0
Note: See TracTickets for help on using tickets.