RETURN documentation block for cloud facts module

Archives Ansible Project
1

Hello,

I wrote a new module for AWS to gather codedeploy facts. When I submitted the pull request, https://github.com/ansible/ansible-modules-extras/pull/1445, travis failed the build. Below is the comment I added to the PR for why it is failing. I’m hoping that someone can help me write a correct RETURN documentation block for a module that returns different data depending on what facts you ask the module to get. I’m guessing more eyes will see this than a pull request.

Thanks!

After a lot of digging, I see that ansible-validate-modules is complaining that there is no RETURN documentation block. This wasn’t immediately obvious to a new module author. Especially when almost all the existing modules are missing it.

$ ../ansible/hacking/test-module -m cloud/amazon/codedeploy_facts.py -a "query=list_applications"
* including generated source, if any, saving to: /home/czeeb/.ansible_module_generated
* this may offset any line numbers in tracebacks/debuggers!
***********************************
RAW OUTPUT
{"applications": ["TestApplication"], "changed": false, "ResponseMetadata": {"HTTPStatusCode": 200, "RequestId": "03717d2c-b0d5-11e5-b101-e1a0e3fb23ac"}}

***********************************
PARSED OUTPUT
{
    "ResponseMetadata": {
        "HTTPStatusCode": 200, 
        "RequestId": "03717d2c-b0d5-11e5-b101-e1a0e3fb23ac"
    }, 
    "applications": [
        "TestApplication"
    ], 
    "changed": false
}

$ ../ansible/hacking/test-module -m cloud/amazon/codedeploy_facts.py -a "query=list_deployments application_name=TestApplication deployment_group_name=Production"
* including generated source, if any, saving to: /home/czeeb/.ansible_module_generated
* this may offset any line numbers in tracebacks/debuggers!
***********************************
RAW OUTPUT
{"changed": false, "ResponseMetadata": {"HTTPStatusCode": 200, "RequestId": "72531c13-b0d5-11e5-89e2-873c8c0b03be"}, "deployments": ["d-74Y1HLWZC", "d-L0MIOT00D", "d-UB2OEGXZC", "d-1BEUEMXZC", "d-UW5VQU00D", "d-CVWS8K10D", "d-UAO4EI60D", "d-Q6HMEI30D", "d-XWDF2AZZC", "d-C98D50XZC", "d-IY542U70D", "d-XC4GOZ20D"]}

***********************************
PARSED OUTPUT
{
    "ResponseMetadata": {
        "HTTPStatusCode": 200, 
        "RequestId": "72531c13-b0d5-11e5-89e2-873c8c0b03be"
    }, 
    "changed": false, 
    "deployments": [
        "d-74Y1HLWZC", 
        "d-L0MIOT00D", 
        "d-UB2OEGXZC", 
        "d-1BEUEMXZC", 
        "d-UW5VQU00D", 
        "d-CVWS8K10D", 
        "d-UAO4EI60D", 
        "d-Q6HMEI30D", 
        "d-XWDF2AZZC", 
        "d-C98D50XZC", 
        "d-IY542U70D", 
        "d-XC4GOZ20D"
    ]
}

Given the above example output for two of the query types for the codedeploy_facts module is the following a correct RETURN block? Each query type returns different output, which is the part I’m not too sure on how to put in the documentation. There aren’t any other _facts modules that have a RETURN block that I can use as an example to work from.

applications:
  description: List of applications
  returned: success
  type: list
  sample:
    [
      "TestApplication",
      "AnotherTestApplication"
    ]

deployments:
  description: List of deployments
  returned: success
  type: list
  sample:
    [
      "d-74Y1HLWZC", 
      "d-XC4GOZ20D"
    ]