Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Add "idempotence check" section to module docs #21299
Documentation generated by modules
OS / ENVIRONMENT
Add a section to module documentation that describes how the idempotence check is implemented.
STEPS TO REPRODUCE
For many modules, the logic used to implement the idempotence check isn't obvious. For example, the ec2_vpc_route_table module isn't idempotent if you don't specify tags. This information is present in the docs, in the description of the "lookup" option, but I missed it at first because I didn't read the documentation of every single option.
I think it would improve the usability of the module documentation if there was a separate "Idempotence check" section, just like there is currently an "Examples" and "Return values" section. Module authors can then specify explicitly how they are implementing the check.
This is a good idea, but adding a specific section globally to all modules to accommodate the few very complex modules is overkill. This would also further complicate the documentation section of modules, which we do not want to do.
A complex explanation like this is bette suited to a README file in a collection.
To discuss this further, please reach out on IRC or the mailing list:
* IRC: #ansible on irc.freenode.net