homebrew_cask: Update documentation and examples (#66073)

* properly document ``upgrade`` option as an alias to ``upgrade_all``, and not a separate option
* Update documentation.
* Update examples.

Fixes: #34696

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/modules/packaging/os/homebrew_cask.py

@@ -1,8 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2013, Daniel Jaouen <dcj24@cornell.edu>
+# Copyright: (c) 2013, Daniel Jaouen <dcj24@cornell.edu>
-# (c) 2016, Indrajit Raychaudhuri <irc+code@indrajit.com>
+# Copyright: (c) 2016, Indrajit Raychaudhuri <irc+code@indrajit.com>
 #
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
@@ -10,131 +10,143 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
     'status': ['preview'],
-                    'supported_by': 'community'}
+    'supported_by': 'community'
+}
 
 
 DOCUMENTATION = '''
 ---
 module: homebrew_cask
 author:
-    - "Indrajit Raychaudhuri (@indrajitr)"
+- "Indrajit Raychaudhuri (@indrajitr)"
-    - "Daniel Jaouen (@danieljaouen)"
+- "Daniel Jaouen (@danieljaouen)"
-    - "Enric Lluelles (@enriclluelles)"
+- "Enric Lluelles (@enriclluelles)"
 requirements:
-   - "python >= 2.6"
+- "python >= 2.6"
-short_description: Install/uninstall homebrew casks.
+short_description: Install and uninstall homebrew casks.
 description:
-    - Manages Homebrew casks.
+- Manages Homebrew casks.
 version_added: "1.6"
 options:
   name:
     description:
-            - name of cask to install/remove
+    - Name of cask to install or remove.
     required: true
     aliases: ['pkg', 'package', 'cask']
+    type: list
   path:
     description:
     - "':' separated list of paths to search for 'brew' executable."
     default: '/usr/local/bin'
+    type: path
   state:
     description:
-            - state of the cask
+    - State of the cask.
     choices: [ 'present', 'absent', 'upgraded' ]
     default: present
+    type: str
   sudo_password:
     description:
     - The sudo password to be passed to SUDO_ASKPASS.
     required: false
     version_added: 2.8
+    type: str
   update_homebrew:
     description:
-            - update homebrew itself first. Note that C(brew cask update) is
+    - Update homebrew itself first.
-              a synonym for C(brew update).
+    - Note that C(brew cask update) is a synonym for C(brew update).
     type: bool
     default: 'no'
     aliases: ['update-brew']
     version_added: "2.2"
   install_options:
     description:
-            - options flags to install a package
+    - Options flags to install a package.
     aliases: ['options']
     version_added: "2.2"
+    type: list
   accept_external_apps:
     description:
-            - allow external apps
+    - Allow external apps.
     type: bool
     default: 'no'
     version_added: "2.5.0"
   upgrade_all:
     description:
-            - upgrade all casks (mutually exclusive with `upgrade`)
+    - Upgrade all casks.
-        type: bool
+    - Mutually exclusive with C(upgraded) state.
-        default: 'no'
-        version_added: "2.5.0"
-    upgrade:
-        description:
-            - upgrade all casks (mutually exclusive with `upgrade_all`)
     type: bool
     default: 'no'
     version_added: "2.5.0"
+    aliases: ['upgrade']
   greedy:
     description:
-            - upgrade casks that auto update; passes --greedy to brew cask
+    - Upgrade casks that auto update.
-              outdated when checking if an installed cask has a newer version
+    - Passes --greedy to brew cask outdated when checking
-              available
+      if an installed cask has a newer version available.
     type: bool
     default: 'no'
     version_added: "2.7.0"
 '''
 EXAMPLES = '''
-- homebrew_cask:
+- name: Install cask
+  homebrew_cask:
     name: alfred
     state: present
 
-- homebrew_cask:
+- name: Remove cask
+  homebrew_cask:
     name: alfred
     state: absent
 
-- homebrew_cask:
+- name: Install cask with install options
+  homebrew_cask:
     name: alfred
     state: present
     install_options: 'appdir=/Applications'
 
-- homebrew_cask:
+- name: Install cask with install options
+  homebrew_cask:
     name: alfred
     state: present
     install_options: 'debug,appdir=/Applications'
 
-- homebrew_cask:
+- name: Allow external app
+  homebrew_cask:
     name: alfred
     state: present
     accept_external_apps: True
 
-- homebrew_cask:
+- name: Remove cask with force option
+  homebrew_cask:
     name: alfred
     state: absent
     install_options: force
 
-- homebrew_cask:
+- name: Upgrade all casks
+  homebrew_cask:
     upgrade_all: true
 
-- homebrew_cask:
+- name: Upgrade given cask with force option
+  homebrew_cask:
     name: alfred
     state: upgraded
     install_options: force
 
-- homebrew_cask:
+- name: Upgrade cask with greedy option
+  homebrew_cask:
     name: 1password
     state: upgraded
     greedy: True
 
-- homebrew_cask:
+- name: Using sudo password for installing cask
+  homebrew_cask:
     name: wireshark
     state: present
     sudo_password: "{{ ansible_become_pass }}"
-
 '''
 
 import os

test/sanity/ignore.txt

@@ -5097,11 +5097,8 @@ lib/ansible/modules/packaging/os/homebrew.py validate-modules:doc-missing-type
 lib/ansible/modules/packaging/os/homebrew.py validate-modules:parameter-invalid
 lib/ansible/modules/packaging/os/homebrew.py validate-modules:parameter-type-not-in-doc
 lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:doc-choices-do-not-match-spec
-lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:doc-missing-type
 lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:doc-required-mismatch
-lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:parameter-documented-multiple-times
 lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:parameter-invalid
-lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:parameter-type-not-in-doc
 lib/ansible/modules/packaging/os/homebrew_tap.py validate-modules:doc-missing-type
 lib/ansible/modules/packaging/os/homebrew_tap.py validate-modules:parameter-type-not-in-doc
 lib/ansible/modules/packaging/os/layman.py validate-modules:doc-missing-type