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

Project Discussions Collection Development
, , , ,
1

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
2

/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
3

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

1 Like
4

I probably won’t have time to check it out until Friday, but I will definitely check it out (and test it) :slight_smile:

5

I added some comments; this is a really great feature and I’m looking forward to be able to use it!

One thing unrelated to the PR: maybe we should add some way to flag these common return values in a way that antsibull-doc can render them slightly different so it’s easier to spot that they are common return values, as opposed to “regular” (and thus more important) return values. This could be done by adding another key, like:

stdout:
  description: blabla
  type: str
  returned: failure
  common_return_value: true  # <--- here we go!

Right now ansible-doc will already display this (as common_return_value: true, which could be made nicer), but the sanity tests and antsibull-doc will complain (unexpected extra keys).

What do everyone think - is this actually necessary, and if yes, how should it look like and work?