Right now the Ansible collection inclusion requirements on CI testing explicitly state that undocumented-parameter is one of the errors you MUST NOT ignore in tests/sanity/ignore-*.txt. Some collections in Ansible violate this rule, but (at least the cases I know of) for good reasons.
Proposal: update the collection requirements so that undocumented-parameter in tests/sanity/ignore-*.txt is allowed in specific circumstances:
deprecated parameters;
internal parameters used to transport data from an action plugin to a module.
Exception 1 makes sense to me. Actually, I think it might be worth to reconsider the absolute ban of all ignores for deprecated parameters.
I’m not 100% sure about exception 2. Is it possible to mark a parameter as (collection) internal? Your proposal makes sense, but this would make it easier IMHO: I think it would be easier to (automatically) allow more ignores if parameters are marked as internal only. If it isn’t possible to have collection internal paramaters for modules we might have to talk to the core team to make it possible.
Why not just document it and say it’s for internal use only. While I would love for a way to explicitly mark something as internal only so you don’t have to document it at all, I find that using the ignore files is the wrong thing for something like this.
I find it very strange to document options that cannot (and must not) be used. (Same as for modules/plugins/roles for internal use of a collection.)
If the users provide values for these options, in the best case they receive an error message, and in the worst case the value is simply ignored. So why should they be listed in the documentation at all? We don’t document other random names that cannot be used as options for a module/plugin/role either.
This was discussed at a core meeting: Meetbot Logs I don’t remember the details, but the result was that nothing happened, and we still have to add ignore.txt entries that globally disable some error classes for a module/plugin…
I find it very strange to document options that cannot (and must not) be used. (Same as for modules/plugins/roles for internal use of a collection.)
Sure but I find it stranger to ignore an explicit check rather than just 2-3 lines saying this is internal and not to use. My preference would be to have a common mechanism to mark options as internal/do not use so they don’t have to be documented but turning off the check for the whole documentation might lead to other errors falling through. In the current landscape documenting them as internal to me is the lesser of two evils here.
With that change, attempting to set an option with set_option or set_options that isn’t documented, or is documented with a wrong/incompatible type to its value, will raise an exception.
I wonder if in some cases, that might end up requiring documentation of internal options used in action plugins (though I guess they just would not use config manager).
I would prefer something like that, but right now it’s not possible, and it doesn’t look like it will change anytime soon.