Add doctests

CHANGELOG

@@ -14,6 +14,7 @@ Version 2.8.1 (WIP)
 :Maintainer: Sébastien Celles <s.celles@gmail.com>
 
 * Issue #77 (PR #47). Convert multiple tests into pytest.mark.parametrize
+* Issue #89 (PR #90). Add doctests.
 
 Version 2.8.0
 =============

semver.py

@@ -46,6 +46,19 @@ def parse(version):
              and 'prerelease'. The prerelease or build keys can be None
              if not provided
     :rtype: dict
+
+    >>> import semver
+    >>> ver = semver.parse('3.4.5-pre.2+build.4')
+    >>> ver['major']
+    3
+    >>> ver['minor']
+    4
+    >>> ver['patch']
+    5
+    >>> ver['prerelease']
+    'pre.2'
+    >>> ver['build']
+    'build.4'
     """
     match = _REGEX.match(version)
     if match is None:
@@ -69,12 +82,6 @@ class VersionInfo(collections.namedtuple(
     :param int patch: version when you make backwards-compatible bug fixes.
     :param str prerelease: an optional prerelease string
     :param str build: an optional build string
-
-    >>> import semver
-    >>> ver = semver.parse('3.4.5-pre.2+build.4')
-    >>> ver
-    {'build': 'build.4', 'major': 3, 'minor': 4, 'patch': 5,
-    'prerelease': 'pre.2'}
     """
     __slots__ = ()
 
@@ -127,6 +134,19 @@ def parse_version_info(version):
     :param version: version string
     :return: a :class:`VersionInfo` instance
     :rtype: :class:`VersionInfo`
+
+    >>> import semver
+    >>> version_info = semver.parse_version_info("3.4.5-pre.2+build.4")
+    >>> version_info.major
+    3
+    >>> version_info.minor
+    4
+    >>> version_info.patch
+    5
+    >>> version_info.prerelease
+    'pre.2'
+    >>> version_info.build
+    'build.4'
     """
     parts = parse(version)
     version_info = VersionInfo(
@@ -190,6 +210,14 @@ def compare(ver1, ver2):
     :return: The return value is negative if ver1 < ver2,
              zero if ver1 == ver2 and strictly positive if ver1 > ver2
     :rtype: int
+
+    >>> import semver
+    >>> semver.compare("1.0.0", "2.0.0")
+    -1
+    >>> semver.compare("2.0.0", "1.0.0")
+    1
+    >>> semver.compare("2.0.0", "2.0.0")
+    0
     """
 
     v1, v2 = parse(ver1), parse(ver2)
@@ -210,6 +238,12 @@ def match(version, match_expr):
           !=  not equal
     :return: True if the expression matches the version, otherwise False
     :rtype: bool
+
+    >>> import semver
+    >>> semver.match("2.0.0", ">=1.0.0")
+    True
+    >>> semver.match("1.0.0", ">1.0.0")
+    False
     """
     prefix = match_expr[:2]
     if prefix in ('>=', '<=', '==', '!='):
@@ -245,6 +279,10 @@ def max_ver(ver1, ver2):
     :param ver2: version string 2
     :return: the greater version of the two
     :rtype: :class:`VersionInfo`
+
+    >>> import semver
+    >>> semver.max_ver("1.0.0", "2.0.0")
+    '2.0.0'
     """
     cmp_res = compare(ver1, ver2)
     if cmp_res == 0 or cmp_res == 1:
@@ -260,6 +298,10 @@ def min_ver(ver1, ver2):
     :param ver2: version string 2
     :return: the smaller version of the two
     :rtype: :class:`VersionInfo`
+
+    >>> import semver
+    >>> semver.min_ver("1.0.0", "2.0.0")
+    '1.0.0'
     """
     cmp_res = compare(ver1, ver2)
     if cmp_res == 0 or cmp_res == -1:
@@ -278,6 +320,10 @@ def format_version(major, minor, patch, prerelease=None, build=None):
     :param str build: the optional build part of a version
     :return: the formatted string
     :rtype: str
+
+    >>> import semver
+    >>> semver.format_version(3, 4, 5, 'pre.2', 'build.4')
+    '3.4.5-pre.2+build.4'
     """
     version = "%d.%d.%d" % (major, minor, patch)
     if prerelease is not None:
@@ -308,6 +354,10 @@ def bump_major(version):
     :param: version string
     :return: the raised version string
     :rtype: str
+
+    >>> import semver
+    >>> semver.bump_major("3.4.5")
+    '4.0.0'
     """
     verinfo = parse(version)
     return format_version(verinfo['major'] + 1, 0, 0)
@@ -319,6 +369,10 @@ def bump_minor(version):
     :param: version string
     :return: the raised version string
     :rtype: str
+
+    >>> import semver
+    >>> semver.bump_minor("3.4.5")
+    '3.5.0'
     """
     verinfo = parse(version)
     return format_version(verinfo['major'], verinfo['minor'] + 1, 0)
@@ -330,6 +384,10 @@ def bump_patch(version):
     :param: version string
     :return: the raised version string
     :rtype: str
+
+    >>> import semver
+    >>> semver.bump_patch("3.4.5")
+    '3.4.6'
     """
     verinfo = parse(version)
     return format_version(verinfo['major'], verinfo['minor'],
@@ -343,6 +401,9 @@ def bump_prerelease(version, token='rc'):
     :param token: defaults to 'rc'
     :return: the raised version string
     :rtype: str
+
+    >>> bump_prerelease('3.4.5', 'dev')
+    '3.4.5-dev.1'
     """
     verinfo = parse(version)
     verinfo['prerelease'] = _increment_string(
@@ -359,6 +420,9 @@ def bump_build(version, token='build'):
     :param token: defaults to 'build'
     :return: the raised version string
     :rtype: str
+
+    >>> bump_build('3.4.5-rc.1+build.9')
+    '3.4.5-rc.1+build.10'
     """
     verinfo = parse(version)
     verinfo['build'] = _increment_string(
@@ -374,6 +438,14 @@ def finalize_version(version):
     :param version: version string
     :return: the finalized version string
     :rtype: str
+
+    >>> finalize_version('1.2.3-rc.5')
+    '1.2.3'
     """
     verinfo = parse(version)
     return format_version(verinfo['major'], verinfo['minor'], verinfo['patch'])
+
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod()

tox.ini

@@ -5,7 +5,7 @@ envlist =
     pypy
 
 [testenv]
-commands = py.test -q
+commands = py.test -q  --doctest-modules
 deps = pytest
 setenv =
     PIP_DISABLE_PIP_VERSION_CHECK = 1