updated docs to reflect list/loop lack of sqashing (#32522)

* updated docs to reflect list/loop lack of sqashing

* fix dnf

* line len

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

@@ -68,6 +68,7 @@ options:
     choices: [ "yes", "no" ]
 notes:
   - '"name" and "upgrade" are mutually exclusive.'
+  - When used with a `loop:` each package will be processed individually, it is much more efficient to pass the list directly to the `name` option.
 '''
 
 EXAMPLES = '''

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

@@ -26,10 +26,8 @@ version_added: "0.0.2"
 options:
   name:
     description:
-      - A package name, like C(foo), or package specifier with version, like C(foo=1.0). Name wildcards (fnmatch) like C(apt*) and version wildcards
+      - A list of package names, like C(foo), or package specifier with version, like C(foo=1.0).
-        like C(foo=1.0*) are also supported.  Note that the apt-get commandline supports implicit regex matches here but we do not because it can let
+        Name wildcards (fnmatch) like C(apt*) and version wildcards like C(foo=1.0*) are also supported.
-        typos through easier (If you typo C(foo) as C(fo) apt-get would install packages that have "fo" in their name with a warning and a prompt for
-        the user.  Since we don't have warnings and prompts before installing we disallow this.  Use an explicit fnmatch pattern if you want wildcarding)
     required: false
     default: null
     aliases: [ 'pkg', 'package' ]
@@ -145,6 +143,10 @@ notes:
    - Three of the upgrade modes (C(full), C(safe) and its alias C(yes)) required C(aptitude) up to 2.3, since 2.4 C(apt-get) is used as a fall-back.
    - apt starts newly installed services by default, this is what the underlying tooling does,
      to avoid this you can set the ``RUNLEVEL`` environment variable to 1.
+   - The apt-get commandline supports implicit regex matches here but we do not because it can let typos through easier
+     (If you typo C(foo) as C(fo) apt-get would install packages that have "fo" in their name with a warning and a prompt for the user.
+     Since we don't have warnings and prompts before installing we disallow this.Use an explicit fnmatch pattern if you want wildcarding)
+   - When used with a `loop:` each package will be processed individually, it is much more efficient to pass the list directly to the `name` option.
 '''
 
 EXAMPLES = '''

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

@@ -25,9 +25,9 @@ description:
 options:
   name:
     description:
-      - >
+      - "A list of package names, or package specifier with version, like C(name-1.0)
-        Package name, or package specifier with version, like C(name-1.0). When using state=latest, this can be '*' which means run: dnf -y update.
+        When using state=latest, this can be '*' which means run: dnf -y update.
-        You can also pass a url or a local path to a rpm file.
+        You can also pass a url or a local path to a rpm file."
     required: true
     default: null
     aliases: []
@@ -95,12 +95,12 @@ options:
     required: false
     choices: [ "yes", "no" ]
     version_added: "2.4"
-
+notes:
-notes: ["autoremove requires dnf >= 2.0.1"]
+  - When used with a `loop:` each package will be processed individually, it is much more efficient to pass the list directly to the `name` option.
-# informational: requirements for nodes
 requirements:
   - "python >= 2.6"
   - python-dnf
+  - for the autoremove option you need dnf >= 2.0.1"
 author:
   - '"Igor Gnatenko (@ignatenkobrain)" <i.gnatenko.brain@gmail.com>'
   - '"Cristian van Ee (@DJMuggs)" <cristian at cvee.org>'

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

@@ -34,16 +34,15 @@ version_added: "1.1"
 options:
     name:
         description:
-            - name of package to install/remove
+            - list of names of packages to install/remove
         required: false
         default: None
         aliases: ['pkg', 'package', 'formula']
     path:
         description:
-            - >
+            - "A ':' separated list of paths to search for 'brew' executable.
-              ':' separated list of paths to search for 'brew' executable. Since A package (I(formula) in homebrew parlance) location is prefixed
+              Since a package (I(formula) in homebrew parlance) location is prefixed relative to the actual path of I(brew) command,
-              relative to the actual path of I(brew) command, providing an alternative I(brew) path enables managing different set of packages in an
+              providing an alternative I(brew) path enables managing different set of packages in an alternative location in the system."
-              alternative location in the system.
         required: false
         default: '/usr/local/bin'
     state:
@@ -73,7 +72,9 @@ options:
         default: null
         aliases: ['options']
         version_added: "1.4"
-notes:  []
+notes:
+  - When used with a `loop:` each package will be processed individually,
+    it is much more efficient to pass the list directly to the `name` option.
 '''
 EXAMPLES = '''
 # Install formula foo with 'brew' in default path (C(/usr/local/bin))

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

@@ -27,7 +27,7 @@ requirements:
 options:
     name:
         description:
-        - Name of the package.
+        - A name or a list of names of the packages.
         required: yes
     state:
         description:
@@ -66,6 +66,9 @@ options:
         type: bool
         default: 'no'
         version_added: "2.3"
+notes:
+  - When used with a `loop:` each package will be processed individually,
+    it is much more efficient to pass the list directly to the `name` option.
 '''
 
 EXAMPLES = '''

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

@@ -18,8 +18,7 @@ DOCUMENTATION = '''
 module: pacman
 short_description: Manage packages with I(pacman)
 description:
-    - Manage packages with the I(pacman) package manager, which is used by
+    - Manage packages with the I(pacman) package manager, which is used by Arch Linux and its variants.
-      Arch Linux and its variants.
 version_added: "1.0"
 author:
     - Indrajit Raychaudhuri (@indrajitr)
@@ -28,7 +27,7 @@ author:
 options:
     name:
         description:
-            - Name of the package to install, upgrade, or remove.
+            - Name or list of names of the packages to install, upgrade, or remove.
         aliases: [ package, pkg ]
 
     state:
@@ -69,6 +68,9 @@ options:
         type: bool
         default: no
         version_added: "2.0"
+notes:
+  - When used with a `loop:` each package will be processed individually,
+    it is much more efficient to pass the list directly to the `name` option.
 '''
 
 RETURN = '''

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

@@ -23,13 +23,12 @@ DOCUMENTATION = '''
 module: pkgng
 short_description: Package manager for FreeBSD >= 9.0
 description:
-    - Manage binary packages for FreeBSD using 'pkgng' which
+    - Manage binary packages for FreeBSD using 'pkgng' which is available in versions after 9.0.
-      is available in versions after 9.0.
 version_added: "1.2"
 options:
     name:
         description:
-            - Name of package to install/remove.
+            - Name or list of names of packages to install/remove.
         required: true
     state:
         description:
@@ -86,7 +85,9 @@ options:
         default: no
 author: "bleader (@bleader)"
 notes:
-    - When using pkgsite, be careful that already in cache packages won't be downloaded again.
+  - When using pkgsite, be careful that already in cache packages won't be downloaded again.
+  - When used with a `loop:` each package will be processed individually,
+    it is much more efficient to pass the list directly to the `name` option.
 '''
 
 EXAMPLES = '''

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

@@ -24,14 +24,12 @@ description:
 options:
   name:
     description:
-      - Package name, or package specifier with version, like C(name-1.0).
+      - A package name , or package specifier with version, like C(name-1.0).
-        If a previous version is specified, the task also needs to turn
+      - If a previous version is specified, the task also needs to turn C(allow_downgrade) on.
-        C(allow_downgrade) on. See the C(allow_downgrade) documentation for
+        See the C(allow_downgrade) documentation for caveats with downgrading packages.
-        caveats with downgrading packages. When using state=latest, this can
+      - When using state=latest, this can be '*' which means run C(yum -y update).
-        be '*' which means run C(yum -y update).  You can also pass a url
+      - You can also pass a url or a local path to a rpm file (using state=present).
-        or a local path to a rpm file (using state=present). To operate on
+        To operate on several packages this can accept a comma separated list of packages or (as of 2.0) a list of packages.
-        several packages this can accept a comma separated list of packages
-        or (as of 2.0) a list of packages.
     required: true
     aliases: [ pkg ]
   exclude:
@@ -130,10 +128,8 @@ options:
     default: "no"
     version_added: "2.4"
 notes:
-  - When used with a loop of package names in a playbook, ansible optimizes
+  - When used with a `loop:` each package will be processed individually,
-    the call to the yum module.  Instead of calling the module with a single
+    it is much more efficient to pass the list directly to the `name` option.
-    package each time through the loop, ansible calls the module once with all
-    of the package names from the loop.
   - In versions prior to 1.9.2 this module installed and removed each package
     given to the yum module separately. This caused problems when packages
     specified by filename or url had to be installed or removed together. In

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

@@ -38,7 +38,7 @@ description:
 options:
     name:
         description:
-        - Package name C(name) or package specifier.
+        - Package name C(name) or package specifier or a list of either.
         - Can include a version like C(name=1.0), C(name>3.4) or C(name<=2.7). If a version is given, C(oldpackage) is implied and zypper is allowed to
           update the package within the version range given.
         - You can also pass a url or a local path to a rpm file.
@@ -107,7 +107,9 @@ options:
         description:
           - Add additional options to C(zypper) command.
           - Options should be supplied in a single line as if given in the command line.
-
+notes:
+  - When used with a `loop:` each package will be processed individually,
+    it is much more efficient to pass the list directly to the `name` option.
 # informational: requirements for nodes
 requirements:
     - "zypper >= 1.0  # included in openSuSE >= 11.1 or SuSE Linux Enterprise Server/Desktop >= 11.0"