[PR #12290/3f3149a2 backport][stable-12] jenkins_plugin: improved descriptions for a parameter and a return value (#12335)

jenkins_plugin: improved descriptions for a parameter and a return value (#12290)

* Improved descriptions for a parameter and a return value

- Improved description of parameter "name".
- Improved description of return value "plugin".
- Added note about unique identifier of Jenkins plugins.

* Fixed documentation syntax in plugins/modules/jenkins_plugin.py



* Removed the point in note with incorrect syntax and using single-quotes to enclose double-quotes

* Added pointer to notes section for more information



---------


(cherry picked from commit 3f3149a25d)

Co-authored-by: Sonal Karmakar <234934724+sonalkarmakar@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/modules/jenkins_plugin.py

@@ -37,7 +37,8 @@ options:
   name:
     type: str
     description:
-      - Plugin name.
+      - Unique plugin ID obtained from L(Jenkins Plugin Index, https://plugins.jenkins.io).
+        See the notes for more information.
     required: true
   owner:
     type: str
@@ -134,6 +135,9 @@ options:
     default: true
 
 notes:
+  - 'Jenkins plugins are required to have I(unique identifiers based on their name), which are used in Plugin Index webpage and
+    URL slug, C(update-center.json), and C(plugin-versions.json). For example: "C(role-strategy)" for the plugin named Role-based
+    Authentication Strategy (U(https://plugins.jenkins.io/role-strategy)).'
   - Plugin installation should be run under root or the same user which owns the plugin files on the disk. Only if the plugin
     is not installed yet and no version is specified, the API installation is performed which requires only the Web UI credentials.
   - It is necessary to notify the handler or call the M(ansible.builtin.service) module to restart the Jenkins service after
@@ -319,7 +323,7 @@ EXAMPLES = r"""
 
 RETURN = r"""
 plugin:
-  description: Plugin name.
+  description: Unique plugin ID based on plugin name.
   returned: success
   type: str
   sample: build-pipeline-plugin