Allow to mark module parameters as undocumented / private

[felixfontein]

Summary

Right now modules that come with action plugins often have some 'private' module parameters that are used by the action plugin, and should not be shown to the user in the documentation. Unfortunately the sanity tests complain about this, and one has to add ignore.txt rules to shut them up. Even more unfortunately, these ignore.txt rules can easily hide real mistakes in the documentation.

I propose to make it possible to explicitly mark options as undocumented or private, so that the sanity tests can enforce that these are undocumented, and no ignore.txt entries are needed.

A more concrete proposal would be to add something to the argument spec, for example some_option=dict(type='str', undocumented=True). (Adding it somewhere to DOCUMENTATION instead makes it show up in the ansible-doc output.)

Issue Type

Feature Idea

Component Name

module argument spec

Additional Information

Grep for validate-modules:undocumented-parameter in test/sanity/ignore.txt in ansible/ansible:

lib/ansible/modules/command.py validate-modules:undocumented-parameter
lib/ansible/modules/copy.py validate-modules:undocumented-parameter
lib/ansible/modules/file.py validate-modules:undocumented-parameter
lib/ansible/modules/stat.py validate-modules:undocumented-parameter
lib/ansible/modules/yum_repository.py validate-modules:undocumented-parameter

There are multiple other entries for the same reason.

Code of Conduct

• I agree to follow the Ansible Code of Conduct

[ansibot]

Files identified in the description:
None

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[s-hertel]

Depends on #79720