snap: improve documentation (#8972)

* plugins/modules/snap: improve documentation

Signed-off-by: Lincoln Wallace <[email protected]>

* undo helper setence about finding avaible snaps.

Co-authored-by: Farshid Tavakolizadeh <[email protected]>

* wip: adress reviews

Signed-off-by: Lincoln Wallace <[email protected]>

* fix: revert sentence

Signed-off-by: Lincoln Wallace <[email protected]>

* feat: improve explanation on snap options

Co-authored-by: Farshid Tavakolizadeh <[email protected]>

* clean: remove duplicated and leave reference

Co-authored-by: Alexei Znamensky <[email protected]>

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

Signed-off-by: Lincoln Wallace <[email protected]>

* fix: remove additional dash.

Co-authored-by: Farshid Tavakolizadeh <[email protected]>

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

Signed-off-by: Lincoln Wallace <[email protected]>

* refact: add period.

Co-authored-by: Farshid Tavakolizadeh <[email protected]>

* fix: linter errors

Signed-off-by: Lincoln Wallace <[email protected]>

* fix: remove redundant sentence

Co-authored-by: Alexei Znamensky <[email protected]>

* fix: remove confuse sentence

Co-authored-by: Farshid Tavakolizadeh <[email protected]>

* fix: remove redudant content

Signed-off-by: Lincoln Wallace <[email protected]>

* feat: add missing word

Co-authored-by: Alexei Znamensky <[email protected]>

* refact: remove abreviation

Co-authored-by: Felix Fontein <[email protected]>

* refact: remove abreviation

Co-authored-by: Felix Fontein <[email protected]>

* refact: remove abreviation

Co-authored-by: Felix Fontein <[email protected]>

---------

Signed-off-by: Lincoln Wallace <[email protected]>
Co-authored-by: Farshid Tavakolizadeh <[email protected]>
Co-authored-by: Alexei Znamensky <[email protected]>
Co-authored-by: Felix Fontein <[email protected]>

plugins/modules/snap.py

@@ -1,6 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
+# Copyright (c) 2024, Lincoln Wallace (locnnil) <[email protected]>
 # Copyright (c) 2021, Alexei Znamensky (russoz) <[email protected]>
 # Copyright (c) 2021, Marcus Rickert <[email protected]>
 # Copyright (c) 2018, Stanislas Lange (angristan) <[email protected]>
@@ -31,8 +32,7 @@
             - 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 @@
         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 @@
             - 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) <[email protected]>