How should presence of common return values in modules be documented?

Ansible documentation contains a list of common return values (Return Values — Ansible Community Documentation) that are also linked from every module documentation page (example). So far I think the recommendation is to not explicitly document these return values in modules (unless there’s something special about them, like they’re using another type as usual etc.) - or at least I think that is a recommentation, I’ve been following it for a long time, but I cannot find any source for it right now.

In community.general we removed documentation for such common return values from modules (remove common return values from docs by russoz · Pull Request #10485 · ansible-collections/community.general · GitHub), but @flowerysong pointed out (correctly!) that this is also not so great because now there is no indication which modules actually return some of these common parameters.

Documenting these return values as regular return values in every module that returns them is IMO not a good idea, since you end up with 100s of slightly different versions of these documentations (and they are tedious to write / copy’n’paste, and then to keep up-to-date). If doc fragments for return values would be there, these could be used to simplify this (but they aren’t yet).

I’m not sure what the best way to proceed here is. (And abusing attributes to document presence of these common return values is not a good idea either - just want to mention that in case anyone wants to throw that into the ring :wink: )

1 Like

/me takes subtle hint to get that PR working soon

FYI, the recommendation does sound like what core proposed for a long time, probably we gave it to you during IRC conversation.

3 Likes

Ok, the PR is ready for review, please check it out and see if this is what you need