Documenting variable suboption types in a module

[John Nelson]

While working on a PR for the win_dns_record module, I ran into a documentation issue that I thought best to ask about, in case anyone can offer any suggestions or otherwise correct my thinking. As background, I'm trying to extend the existing module to support additional DNS record types. Of concern is that the new record types take values that are more nuanced than those currently supported.

---------------

Example #1 (already supported):

• An "A" record is used to map a hostname to an IP address.
• The record's value in this case is the IP address itself. This is a simple (non-compound) value, expressed as a string.
  
• An appropriate way to document this "value" option in this case would include type=list and elements=str.
  

Example #2 (want to add support for this):

• An "MX" record is used to indicate which mail server should receive email for a domain.
• The record's value in this case is a tuple comprised of a priority and a hostname. This is a compound value, which I'd prefer to express as a dict (because names are clearer than list offsets).
• An appropriate way to document this "value" option would still include type=list, but now requires elements=dict (rather than =str) and a suboptions={...} that is specific to MX records.
  

So the problem comes from wanting to support record types that require compound values. (And note that the specific value fields aren't the same for each record type!).

---------------

As far as I can tell, there is no way to specify "conditional" suboptions, or even more than one set of suboptions, even if the backend is made smart enough to handle it (which turns out to be fairly straightforward, incidentally -- I have no concerns on the implementation side).

If true, that suggests I would need to resort to free-form fields, in which case the real documentation exists solely in the examples (which is far from ideal).

---------------

Am I somehow wrong in assuming that suboptions can't be used the way I want? Or is there some other way to nuance them? Some way to add hand-crafted HTML to an option? Other things to try instead?

[James Cassell]

On Thu, Feb 27, 2020, at 2:24 PM, John Nelson wrote:
> While working on a PR for the win_dns_record

> <https://docs.ansible.com/ansible/latest/modules/win_dns_record_module.html> module, I ran into a documentation issue that I thought best to ask about, in case anyone can offer any suggestions or otherwise correct my thinking. As background, I'm trying to extend the existing module to support additional DNS record types. Of concern is that the new record types take *values* that are more nuanced than those currently supported.

>
> ---------------
>
> Example #1 (already supported):

> * An "A" record is used to map a hostname to an IP address.
> * The record's *value* in this case is the IP address itself. This is

> a simple (non-compound) value, expressed as a string.

> * An appropriate way to document this "value" option in this case

> would include type=list and elements=str.
> Example #2 (want to add support for this):

> * An "MX" record is used to indicate which mail server should receive
> email for a domain.
> * The record's *value* in this case is a tuple comprised of a
> *priority* and a *hostname*. This is a compound value, which I'd
> *prefer* to express as a dict (because names are clearer than list
> offsets).
> * An appropriate way to document this "value" option would still

> include type=list, but now requires elements=dict (rather than =str)

> and a suboptions={...} that is *specific* to MX records.

> So the problem comes from wanting to support record types that require

> *compound* values. (And note that the specific value *fields* aren't

> the same for each record type!).
>
> ---------------
>
> As far as I can tell, there is no way to specify "conditional"
> suboptions, or even more than one set of suboptions, even if the
> backend is made smart enough to handle it (which turns out to be fairly
> straightforward, incidentally -- I have no concerns on the

> *implementation* side).

>
> If true, that suggests I would need to resort to free-form fields, in

> which case the *real* documentation exists solely in the examples

> (which is far from ideal).
>
> ---------------
>
> Am I somehow wrong in assuming that suboptions can't be used the way I
> want? Or is there some other way to nuance them? Some way to add
> hand-crafted HTML to an option? Other things to try instead?
>

I think the general recommendation would be to create one module per record type if it gets complex. Share common code using module_utils.

V/r,
James Cassell