adding version to documentation to help out on pycontribs#1016 (pycontribs#1039)

* adding version to documentation to help out on pycontribs#1016

* updating param name from **args to **kwargs and adding some test coverage for it

* adding an example in the method documentation

Co-authored-by: Neefs, Jef <[email protected]>

Author: 2 people

docs/api.rst

@@ -26,6 +26,11 @@ Comment
 
 .. autoclass:: Comment
 
+Version
+=======
+
+.. autoclass:: jira.resources.Version
+
 Worklog
 =======
 

jira/resources.py

@@ -879,10 +879,11 @@ def __init__(self, options, session, raw=None):
             self._parse_raw(raw)
 
     def delete(self, moveFixIssuesTo=None, moveAffectedIssuesTo=None):
-        """Delete this project version from the server.
+        """
+        Delete this project version from the server.
 
-        If neither of the arguments are specified, the version is
-            removed from all issues it is attached to.
+        If neither of the arguments are specified, the version is removed from all
+        issues it is attached to.
 
         :param moveFixIssuesTo: in issues for which this version is a fix
             version, add this argument version to the fix version list
@@ -898,11 +899,32 @@ def delete(self, moveFixIssuesTo=None, moveAffectedIssuesTo=None):
 
         return super(Version, self).delete(params)
 
-    def update(self, **args):
-        """Update this project version from the server. It is prior used to archive versions."""
+    def update(self, **kwargs):
+        """
+        Update this project version from the server. It is prior used to archive versions.
+
+        Refer to Atlassian REST API `documentation`_.
+
+        .. _documentation: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-project-versions/#api-rest-api-2-version-id-put
+
+        :Example:
+
+            .. code-block:: python
+
+                >> version_id = "10543"
+                >> version = JIRA("https://atlassian.org").version(version_id)
+                >> print(version.name)
+                "some_version_name"
+                >> version.update(name="another_name")
+                >> print(version.name)
+                "another_name"
+                >> version.update(archived=True)
+                >> print(version.archived)
+                True
+        """
         data = {}
-        for field in args:
-            data[field] = args[field]
+        for field in kwargs:
+            data[field] = kwargs[field]
 
         super(Version, self).update(**data)
 

tests/tests.py

@@ -1570,6 +1570,17 @@ def test_project_versions(self):
         i.update(fields={"fixVersions": [{"id": version.id}]})
         version.delete()
 
+    def test_update_project_version(self):
+        # given
+        name = "version-%s" % rndstr()
+        version = self.jira.create_version(name, self.project_b, "will be deleted soon")
+        updated_name = "version-%s" % rndstr()
+        # when
+        version.update(name=updated_name)
+        # then
+        self.assertEqual(updated_name, version.name)
+        version.delete()
+
     def test_get_project_version_by_name(self):
         name = "version-%s" % rndstr()
         version = self.jira.create_version(name, self.project_b, "will be deleted soon")