Ansible Module Doc Review

Ansible Module Documentation Review

Ansible modules require comprehensive documentation in specific sections (DOCUMENTATION, EXAMPLES, RETURN) to help users understand what the module does and how to use it. This skill validates completeness and helps fill in missing or placeholder content.

When to Apply

Apply this technique when:

• A module has PLACEHOLDER text in its documentation
• Creating a new module that needs documentation
• Reviewing an existing module for documentation quality
• Updating a module after API changes

Skip this technique when:

• The module already has complete, validated documentation
• Working on internal/utility modules not exposed to users
• Making code-only changes that don't affect the module's behavior

Documentation Requirements

Required Sections

All modules must have these documentation sections properly filled out:

Section Details

DOCUMENTATION.short_description

A concise 1-2 sentence summary of what the module does.

Examples:

• "Manage vCenter resource pools."
• "Gather information about appliance monitoring."

DOCUMENTATION.description

A list of 2-5 sentences describing the module in more detail. Should cover:

• What the module manages or queries
• Key capabilities or operations
• Important context about the resource type

DOCUMENTATION.options

Review all option descriptions to ensure they:

• Explain in plain terms what the option does or means
• Avoid technical jargon where possible
• Clearly state the purpose and effect of the option
• Include relevant API context where helpful

EXAMPLES Section

Must be valid YAML showing Ansible tasks that demonstrate module usage.

Requirements:

• Use fully qualified module name: vmware.vmware_rest.<module_name>
• Show different options and use cases
• Comply with option requirements and types
• Be executable examples that would actually work

For INFO modules:

• Show a minimal example
• Show an example with more parameters

For CRUD modules:

• Showcase different states (present, absent)
• Show a simple example
• Show a more complex example with additional options

Example structure:

- name: Create a resource pool
  vmware.vmware_rest.vcenter_resourcepool:
    name: my-resource-pool
    parent: resgroup-1001
    state: present

- name: Delete a resource pool
  vmware.vmware_rest.vcenter_resourcepool:
    resource_pool: resgroup-1009
    state: absent

Note: Do not include connection parameters (vcenter_hostname, vcenter_username, vcenter_password) in examples - they are implied through the connection_params documentation fragment.

RETURN Section

Must be a valid YAML dictionary documenting return values.

Do NOT document:

• The changed key (standard Ansible return value)
• The diff key (standard Ansible return value)

Each return value must have:

• description: A sentence about what the return value represents
• returned: When the value is returned (e.g., "On success", "When state is present")
• type: Python type (str, dict, list, int, bool)
• sample: Example output (consult API spec for realistic samples)

For INFO modules:

(Hint: is the module name states with appliance_, the id value will never be returned)

The return structure for info modules always includes:

id:
  description: MOID of the queried resource
  returned: When only one resource, with a MOID, was queried
  sample: resgroup-1009
  type: str

value:
  description:
    - Raw output from the API response
    - This output is maintained for consistency with version 4.x and earlier of this collection.
      It is recommended to switch to the info return key for a more consistent and documented output.
  returned: On success
  sample:
    description: ntpd.service
    state: STARTED
  type: raw

info:
  description: A list of detailed information about resources
  returned: On success
  sample:
    - description: ntpd.service
      state: STARTED
  type: list

For CRUD modules:

(Hint: is the module name states with appliance_, the id value will never be returned)

id:
  description: MOID of the managed resource
  returned: When state is present, or when a resource is deleted, or when state is set to a supported action
  sample: resgroup-1009
  type: str

CRUD modules also return the raw API response body:

value:
  description: The raw API response body from the vCenter operation.
  returned: On success
  sample:
    succeeded: true
  type: raw

Step-by-Step Review Process

Step 1: Identify the Module Type

Determine if the module is:

• INFO module: Gathers information (ends with _info)
• CRUD module: Creates/updates/deletes resources (has state parameter)

This determines the expected RETURN structure.

Step 2: Review DOCUMENTATION Section

Check and complete:

1. short_description: Should be concise and clear
2. description: Should be 2-5 sentences providing detail
3. options: Each option should have a clear, plain-language description
4. Are all lines 160 characters or less?

Look for:

• PLACEHOLDER text
• Vague or unclear descriptions
• Missing context about what options do

Step 3: Review EXAMPLES Section

Verify the examples:

1. Are they valid YAML?
2. Do they use the fully qualified module name?
3. Do they demonstrate different use cases appropriately?
4. For CRUD modules: Do they show different states?
5. For INFO modules: Do they show both simple and complex queries?
6. Are the examples realistic and executable?

Step 4: Review RETURN Section

Check return value documentation:

1. For INFO modules: Verify id, value, and info are documented (Hint: is the module name states with appliance_, the id value will never be returned)
2. For CRUD modules: Verify id and value are documented (Hint: is the module name states with appliance_, the id value will never be returned)
3. Ensure each return value has description, returned, type, and sample
4. Verify samples are realistic (check API spec if needed)

Step 5: Consult API Endpoints

For context and validation:

1. Review the module's operation config definitions in plugins/module_utils/_operation_configs.py
2. Check API endpoint specifications for:
   • Available parameters and their meanings
   • Expected return value structures
   • Sample response data