update azure_rm_availabilityset related module document (#56432)

* Update azure_rm_availabilityset.py

lib/ansible/modules/cloud/azure/azure_rm_availabilityset.py

@@ -18,11 +18,12 @@ module: azure_rm_availabilityset
 
 version_added: "2.4"
 
-short_description: Manage Azure availability set.
+short_description: Manage Azure Availability Set
 
 description:
-    - Create, update and delete Azure availability set. An availability set cannot be updated, you will have to
-      recreate one instead. The only update operation will be for the tags.
+    - Create, update and delete Azure Availability Set.
+    - An availability set cannot be updated, you will have to recreate one instead.
+    - The only update operation will be for the tags.
 
 options:
     resource_group:
@@ -35,22 +36,25 @@ options:
         required: true
     state:
         description:
-            - Assert the state of the availability set. Use C(present) to create or update a availability set and
-              C(absent) to delete a availability set.
+            - Assert the state of the availability set.
+            - Use C(present) to create or update a availability set and C(absent) to delete a availability set.
         default: present
         choices:
             - absent
             - present
     location:
         description:
-            - Valid azure location. Defaults to location of the resource group.
+            - Valid Azure location. Defaults to location of the resource group.
     platform_update_domain_count:
         description:
-            - Update domains indicate groups of virtual machines and underlying physical hardware that can be rebooted at the same time. Default is 5.
+            - Update domains indicate groups of virtual machines and underlying physical hardware that can be rebooted at the same time.
+        type: int
         default: 5
     platform_fault_domain_count:
         description:
-            - Fault domains define the group of virtual machines that share a common power source and network switch. Should be between 1 and 3. Default is 3
+            - Fault domains define the group of virtual machines that share a common power source and network switch.
+            - Should be between C(1) and C(3).
+        type: int
         default: 3
     sku:
         description:
@@ -93,13 +97,51 @@ EXAMPLES = '''
 
 RETURN = '''
 state:
-    description: Current state of the availability set
+    description: Current state of the availability set.
     returned: always
-    type: dict
+    type: complex
+    contains:
+        id:
+            description:
+                - Resource ID.
+            type: str
+            sample: "/subscriptions/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/resourceGroups/v-xisuRG/providers/Microsoft.Compute/availabilitySets/myavailabilityset2"
+        location:
+            description:
+                - Location where the resource lives.
+            type: str
+            sample: eastus
+        name:
+            description:
+                - Resource name.
+            type: str
+            sample: myavailabilityset2
+        platform_fault_domain_count:
+            description:
+                - Fault domains values.
+            type: int
+            sample: 2
+        platform_update_domain_count:
+            description:
+                - Update domains values.
+            type: int
+            sample: 5
+        sku:
+            description:
+                - The availability set supports managed disks.
+            type: str
+            sample: Aligned
+        tags:
+            description:
+                - Resource tags.
+            type: dict
+            sample: {env: sandbox}
+
 changed:
     description: Whether or not the resource has changed
     returned: always
     type: bool
+    sample: true
 '''
 
 from ansible.module_utils.azure_rm_common import AzureRMModuleBase

lib/ansible/modules/cloud/azure/azure_rm_availabilityset_facts.py

@@ -17,7 +17,7 @@ module: azure_rm_availabilityset_facts
 
 version_added: "2.4"
 
-short_description: Get availability set facts.
+short_description: Get Azure Availability Set facts
 
 description:
     - Get facts for a specific availability set or all availability sets.
@@ -25,13 +25,13 @@ description:
 options:
     name:
         description:
-            - Limit results to a specific availability set
+            - Limit results to a specific availability set.
     resource_group:
         description:
-            - The resource group to search for the desired availability set
+            - The resource group to search for the desired availability set.
     tags:
         description:
-            - List of tags to be matched
+            - List of tags to be matched.
 
 extends_documentation_fragment:
     - azure
@@ -56,18 +56,53 @@ RETURN = '''
 azure_availabilityset:
     description: List of availability sets dicts.
     returned: always
-    type: list
-    example: [{
-        "location": "eastus2",
-        "name": "myAvailabilitySet",
-        "properties": {
-            "platformFaultDomainCount": 3,
-            "platformUpdateDomainCount": 2,
-            "virtualMachines": []
-        },
-        "sku": "Aligned",
-        "type": "Microsoft.Compute/availabilitySets"
-    }]
+    type: complex
+    contains:
+        location:
+            description:
+                - Location where the resource lives.
+            type: str
+            sample: eastus2
+        name:
+            description:
+                - Resource name.
+            type: str
+            sample: myAvailabilitySet
+        properties:
+            description:
+                - The properties of the resource.
+            type: dict
+            contains:
+                platformFaultDomainCount:
+                    description:
+                        - Fault Domain count.
+                    type: int
+                    sample: 3
+                platformUpdateDomainCount:
+                    description:
+                        - Update Domain count.
+                    type: int
+                    sample: 2
+                virtualMachines:
+                    description:
+                        - A list of references to all virtualmachines in the availability set.
+                    type: list
+                    sample: []
+        sku:
+            description:
+                - Location where the resource lives.
+            type: str
+            sample: Aligned
+        type:
+            description:
+                - Resource type.
+            type: str
+            sample: "Microsoft.Compute/availabilitySets"
+        tags:
+            description:
+                - Resource tags.
+            type: dict
+            sample: { env: sandbox }
 '''
 
 from ansible.module_utils.azure_rm_common import AzureRMModuleBase