Improve docs on `next_patch()`.

Those functions had been forgotten in the docs.

Clarify that `Version('1.0.1-alpha').next_patch()` is
`Version('1.0.1')`, since that version is the smallest non-prerelease
version greater than `Version('1.0.1-alpha')`.

Closes: #67

2 files changed, 52 insertions, 3 deletions

diff --git a/README.rst b/README.rst
index c1d97d2..682a8c7 100644
--- a/README.rst
+++ b/README.rst
@@ -125,15 +125,15 @@ You can also get a new version that represents a bump in one of the version leve
 
 .. code-block:: pycon
 
-    >>> v = semantic_version.Version('0.1.1-pre+build')
+    >>> v = semantic_version.Version('0.1.1+build')
     >>> new_v = v.next_major()
     >>> str(new_v)
     '1.0.0'
-    >>> v = semantic_version.Version('1.1.1-pre+build')
+    >>> v = semantic_version.Version('1.1.1+build')
     >>> new_v = v.next_minor()
     >>> str(new_v)
     '1.2.0'
-    >>> v = semantic_version.Version('1.1.1-pre+build')
+    >>> v = semantic_version.Version('1.1.1+build')
     >>> new_v = v.next_patch()
     >>> str(new_v)
     '1.1.2'
diff --git a/docs/reference.rst b/docs/reference.rst
index 358b2c0..7c91200 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -122,6 +122,55 @@ Representing a version (the Version class)
     .. rubric:: Methods
 
 
+    .. method:: next_major(self)
+
+        Return the next major version, i.e the smallest version strictly greater
+        than the current one with minor and patch set to 0 and no prerelease/build.
+
+        .. code-block:: pycon
+
+            >>> Version('1.0.2').next_major()
+            Version('2.0.0')
+            >>> Version('1.0.0+b3').next_major()
+            Version('2.0.0')
+            >>> Version('1.0.0-alpha').next_major()
+            Version('1.0.0')
+
+    .. method:: next_minor(self)
+
+        Return the next minor version, i.e the smallest version strictly greater
+        than the current one, with a patch level of ``0``.
+
+        .. code-block:: pycon
+
+            >>> Version('1.0.2').next_minor()
+            Version('1.1.0')
+            >>> Version('1.0.0+b3').next_minor()
+            Version('1.1.0')
+            >>> Version('1.1.2-alpha').next_minor()
+            Version('1.2.0')
+            >>> Version('1.1.0-alpha').next_minor()
+            Version('1.1.0')
+
+    .. method:: next_patch(self):
+
+        Return the next patch version, i.e the smallest version strictly
+        greater than the current one with empty :attr:`prerelease` and :attr:`build`.
+
+        .. code-block:: pycon
+
+            >>> Version('1.0.2').next_patch()
+            Version('1.0.3')
+            >>> Version('1.0.2+b3').next_patch()
+            Version('1.0.3')
+            >>> Version('1.0.2-alpha').next_patch()
+            Version('1.0.2')
+
+        .. warning:: The next patch version of a version with a non-empty
+                     :attr:`prerelease` is the version without that
+                     :attr:`prerelease` component: it's the smallest "pure"
+                     patch version strictly greater than that version.
+
     .. method:: __iter__(self)
 
         Iterates over the version components (:attr:`major`, :attr:`minor`,