[PR #8972/a894f8e7 backport][stable-9] snap: improve documentation (#9023)

snap: improve documentation (#8972)

* plugins/modules/snap: improve documentation

Signed-off-by: Lincoln Wallace <lincoln.wallace@canonical.com>

* undo helper setence about finding avaible snaps.

Co-authored-by: Farshid Tavakolizadeh <email@farshid.ws>

* wip: adress reviews

Signed-off-by: Lincoln Wallace <lincoln.wallace@canonical.com>

* fix: revert sentence

Signed-off-by: Lincoln Wallace <lincoln.wallace@canonical.com>

* feat: improve explanation on snap options

Co-authored-by: Farshid Tavakolizadeh <email@farshid.ws>

* clean: remove duplicated and leave reference

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* feat: add note about priviledge scalation and switch sentence position

Signed-off-by: Lincoln Wallace <lincoln.wallace@canonical.com>

* fix: remove additional dash.

Co-authored-by: Farshid Tavakolizadeh <email@farshid.ws>

* feat: reword note and use better doc cross-ref syntax

Signed-off-by: Lincoln Wallace <lincoln.wallace@canonical.com>

* refact: add period.

Co-authored-by: Farshid Tavakolizadeh <email@farshid.ws>

* fix: linter errors

Signed-off-by: Lincoln Wallace <lincoln.wallace@canonical.com>

* fix: remove redundant sentence

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* fix: remove confuse sentence

Co-authored-by: Farshid Tavakolizadeh <email@farshid.ws>

* fix: remove redudant content

Signed-off-by: Lincoln Wallace <lincoln.wallace@canonical.com>

* feat: add missing word

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* refact: remove abreviation

Co-authored-by: Felix Fontein <felix@fontein.de>

* refact: remove abreviation

Co-authored-by: Felix Fontein <felix@fontein.de>

* refact: remove abreviation

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Signed-off-by: Lincoln Wallace <lincoln.wallace@canonical.com>
Co-authored-by: Farshid Tavakolizadeh <email@farshid.ws>
Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit a894f8e7eb)

Co-authored-by: Lincoln Wallace <locnnil@hotmail.com>

plugins/modules/snap.py

@@ -1,6 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
+# Copyright (c) 2024, Lincoln Wallace (locnnil) <lincoln.wallace@canonical.com>
 # Copyright (c) 2021, Alexei Znamensky (russoz) <russoz@gmail.com>
 # Copyright (c) 2021, Marcus Rickert <marcus.rickert@web.de>
 # Copyright (c) 2018, Stanislas Lange (angristan) <angristan@pm.me>
@@ -31,8 +32,7 @@ options:
             - Name of the snaps to be installed.
             - Any named snap accepted by the C(snap) command is valid.
             - >
-              Notice that snap files might require O(dangerous=true) to ignore the error
-              "cannot find signatures with metadata for snap".
+              O(dangerous=true) may be necessary when installing `.snap` files. See O(dangerous) for more details.
         required: true
         type: list
         elements: str
@@ -47,10 +47,13 @@ options:
         type: str
     classic:
         description:
-            - Confinement policy. The classic confinement allows a snap to have
-              the same level of access to the system as "classic" packages,
-              like those managed by APT. This option corresponds to the C(--classic) argument.
-              This option can only be specified if there is a single snap in the task.
+            - Install a snap that has classic confinement.
+            - This option corresponds to the C(--classic) argument of the C(snap install) command.
+            - This level of confinement is permissive, granting full system access,
+              similar to that of traditionally packaged applications that do not use sandboxing mechanisms.
+              This option can only be specified when the task involves a single snap.
+            - See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels.
+
         type: bool
         required: false
         default: false
@@ -69,18 +72,27 @@ options:
             - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied
               to that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will
               only be applied to active snaps.
+            - Options will only be applied when C(state) is set to V(present).
+              This is done after the necessary installation
+              or refresh (upgrade/downgrade) of all the snaps listed in O(name).
+            - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options.
+
         required: false
         type: list
         elements: str
         version_added: 4.4.0
     dangerous:
         description:
-            - Install the given snap file even if there are no pre-acknowledged signatures for it,
-              meaning it was not verified and could be dangerous.
+            - Install the snap in dangerous mode, without validating its assertions and signatures.
+            - This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged.
+            - See U(https://snapcraft.io/docs/install-modes) for more details about installation modes.
         type: bool
         required: false
         default: false
         version_added: 7.2.0
+notes:
+  - Privileged operations, such as installing and configuring snaps, require root priviledges.
+    This is only the case if the user has not logged in to the Snap Store.
 
 author:
     - Victor Carceler (@vcarceler) <vcarceler@iespuigcastellar.xeill.net>