Improve documentation of AttachmentsInterface methods

There's TODO in class description which missing related issue, so documentation of the methods looks related

I am sorry but that's not what this issue is about. That TODO has nothing to do with documentation, AttachedAssetsInterface doesn't document what $attachments can be and also given ✨ Allow additional keys in #attached Needs review I am not sure whether that TODO will ever resolve.

Thank you, updated IS from #3 but the title should be more actionable/precise about what to do

Made an MR with a start to the changes, including some fixes to the documentation - the example of adding a library was wrong, and the list of keys used by core was incomplete.

Curious what's next steps for this one?

Updated for coding standard fixes and then added @see. The changes for coding standards required changes to the list of keys so that section needs review as it is no longer simply a move of code from one file to another.

Awesome. Don't we want to add a @see to the param doxygen on the interface of $attachments / return value of get? The class doxygen is not always immediately visible -- for example on api.drupal.org , in an IDE popup and more.

@Ghost of Drupal Past, Ah, that is step 2 in the remaining tasks. I didn't do that because it just seems odd to have an @see directing to the same file and for file that is only 75 lines. Sorry, I should have commented on that. But, I am happy to be convinced otherwise. Or, we get this improvement in and punt step 2/#12 to another issue. The later is my preference as I prefer incremental doc improvements over the other options.

Current change reads fine

with regards to

punt step 2/#12 to another issue.

do we want a follow up?

longwave → closed merge request !8268

As someone who's opened this file in the past and been confused by this, incremental improvements are welcome. Feel free to open followups to improve this further if anyone thinks it is necessary.

Backported down to 10.3.x as a docs-only fix.

Committed and pushed d820d8ed3e to 11.x and a21edc2188 to 11.0.x and db4e4e5426 to 10.4.x and 723d4d718a to 10.3.x. Thanks!

Automatically closed - issue fixed for 2 weeks with no activity.

I was one of the people who introduced these 2 files in #2407195: Move attachment processing to services and per-type response subclasses → , apologies for not getting the docs better at the time 🫣 (Looks like a simple location swap would've prevented most pain.)