Update docs.

Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>

2 files changed, 66 insertions, 66 deletions

diff --git a/doc/index.rst b/doc/index.rst
index 6e7fdb0..704393f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -87,25 +87,47 @@ The :class:`Spec` object describes a range of accepted versions::
     >>> s = Spec('>=0.1.1')  # At least 0.1.1
     >>> s.match(Version('0.1.1'))
     True
-    >>> s.match(Version('0.1.1-alpha1'))
+    >>> s.match(Version('0.1.1-alpha1'))  # pre-release satisfy version spec
+    True
+    >>> s.match(Version('0.1.0'))
     False
 
-It is also possible to define 'approximate' version specifications::
+Simpler test syntax is also available using the ``in`` keyword::
 
-    >>> s = Spec('~0.1')  # Matches 0.1.*
-    >>> s.match(Version('0.1.0-alpha1'))
+    >>> s = Spec('==0.1.1')
+    >>> Version('0.1.1-alpha1') in s
     True
-    >>> s.match(Version('0.1.9999999999+build99'))
+    >>> Version('0.1.2') in s
+    False
+
+
+Including pre-release identifiers in specifications
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+
+When testing a :class:`Version` against a :class:`Spec`, comparisons are only
+performed for components defined in the :class:`Spec`; thus, a pre-release
+version (``1.0.0-alpha``), while not strictly equal to the non pre-release
+version (``1.0.0``), satisfies the ``==1.0.0`` :class:`Spec`.
+
+Pre-release identifiers will only be compared if included in the :class:`Spec`
+definition or (for the empty pre-release number) if a single dash is appended
+(``1.0.0-``)::
+
+    >>> Version('0.1.0-alpha') in Spec('>=0.1.0')  # No pre-release identifier
     True
-    >>> s.match(Version('0.2.0'))
+    >>> Version('0.1.0-alpha') in Spec('>=0.1.0-')  # Include pre-release in checks
     False
 
-Simpler test syntax is also available using the ``in`` keyword::
+Including build identifiers in specifications
+"""""""""""""""""""""""""""""""""""""""""""""
 
-    >>> s = Spec('~0.1.1')
-    >>> Version('0.1.1-alpha1') in s
+The same rule applies for the build identifier: comparisons will include it only
+if it was included in the :class:`Spec` definition, or - for the unnumbered build
+version - if a single + is appended to the definition(``1.0.0+``, ``1.0.0-alpha+``)::
+
+    >>> Version('1.0.0+build2') in Spec('<=1.0.0')   # Build identifier ignored
     True
-    >>> Version('0.1.2') in s
+    >>> Version('1.0.0+build2') in Spec('<=1.0.0+')  # Include build in checks
     False
 
 
@@ -114,18 +136,20 @@ Combining requirements
 
 In order to express complex version specifications, use the :class:`SpecList` class::
 
-    >>> # At least 0.1.1, not 0.2.X, avoid broken 0.1.5-alpha.
-    >>> sl = SpecList('>=0.1.1,<~0.2,!=0.1.5-alpha')
+    >>> # At least 0.1.1, not 0.2.0, avoid broken 0.1.5-alpha.
+    >>> sl = SpecList('>=0.1.1,<0.2.0,!=0.1.5-alpha')
     >>> sl.match(Version('0.1.1'))
     True
     >>> Version('0.1.1-rc1') in sl
-    False
+    True
     >>> Version('0.1.2') in sl
     True
     >>> Version('0.2.0-alpha') in sl
     False
     >>> Version('0.1.5-alpha') in sl
     False
+    >>> Version('0.1.5-alpha+build2') in sl
+    False
 
 
 Using with Django
diff --git a/doc/reference.rst b/doc/reference.rst
index 6882988..922bdf1 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -252,10 +252,18 @@ rules apply:
 
     This allows to test :class:`Version` objects against the :class:`Spec`::
 
-        >>> Spec('>=0.1.1').match(Version('0.1.1-rc1'))  # pre-release have lower precedence
-        False
-        >>> Version('0.1.1+build2') in Spec('>=0.1.1')   # build version have higher precedence
+        >>> Spec('>=0.1.1').match(Version('0.1.1-rc1'))  # pre-release satisfy conditions
+        True
+        >>> Version('0.1.1+build2') in Spec('>=0.1.1')   # build version satisfy specifications
         True
+        >>>
+        >>> # Use the '-' marker to include the pre-release component in checks
+        >>> Spec('>=0.1.1-').match(Version('0.1.1-rc1')
+        False
+        >>>
+        >>> # Use the '+' marker to include the build identifier in checks
+        >>> Spec('<=0.1.1-alpha+').match(Version('0.1.1-alpha+build1'))
+        False
 
 
     .. rubric:: Attributes
@@ -264,14 +272,13 @@ rules apply:
     .. attribute:: kind
 
         One of :data:`KIND_LT`, :data:`KIND_LTE`, :data:`KIND_EQUAL`, :data:`KIND_GTE`,
-        :data:`KIND_GT`, :data:`KIND_NEQ`, :data:`KIND_LTE_LOOSE`, :data:`KIND_EQ_LOOSE`,
-        :data:`KIND_GTE_LOOSE`, :data:`KIND_NEQ_LOOSE`.
+        :data:`KIND_GT` and :data:`KIND_NEQ`.
 
     .. attribute:: spec
 
         :class:`Version` in the :class:`Spec` description.
 
-        If :attr:`kind` is a ``_LOOSE`` kind, this will be a :attr:`~Version.partial` :class:`Version`.
+        It is alway a :attr:`~Version.partial` :class:`Version`.
 
 
     .. rubric:: Class methods
@@ -293,7 +300,9 @@ rules apply:
 
         Test whether a given :class:`Version` matches this :class:`Spec`::
 
-            >>> Spec('>0.1.1').match(Version('0.1.1-alpha'))
+            >>> Spec('>=0.1.1').match(Version('0.1.1-alpha'))
+            True
+            >>> Spec('>=0.1.1-').match(Version('0.1.1-alpha'))
             False
 
         :param version: The version to test against the spec
@@ -333,21 +342,21 @@ rules apply:
         The kind of 'Less than' specifications::
 
             >>> Version('1.0.0-alpha') in Spec('<1.0.0')
-            True
+            False
 
     .. data:: KIND_LTE
 
         The kind of 'Less or equal to' specifications::
 
             >>> Version('1.0.0-alpha1+build999') in Spec('<=1.0.0-alpha1')
-            False
+            True
 
     .. data:: KIND_EQUAL
 
         The kind of 'equal to' specifications::
 
             >>> Version('1.0.0+build3.3') in Spec('==1.0.0')
-            False
+            True
 
     .. data:: KIND_GTE
 
@@ -361,7 +370,7 @@ rules apply:
         The kind of 'Greater than' specifications::
 
             >>> Version('1.0.0+build667') in Spec('>1.0.1')
-            True
+            False
 
     .. data:: KIND_NEQ
 
@@ -373,39 +382,6 @@ rules apply:
         The kind of 'Almost equal to' specifications
 
 
-    .. data:: KIND_LTE_LOOSE
-
-        The kind of 'Loosely lesser or equal to' specifications::
-
-            >>> Version('1.0.1-alpha+build99') in Spec('<=1.0.1-alpha')
-            False
-            >>> Version('1.0.1-alpha+build99') in Spec('<~1.0.1-alpha')
-            True
-
-    .. data:: KIND_EQ_LOOSE
-
-        The kind of 'Almost equal to' specifications::
-
-            >>> Version('1.0.1-alpha') in Spec('~=1.0.1')
-            True
-
-    .. data:: KIND_GTE_LOOSE
-
-        The kind of 'Loosely greater or equal to' specifications::
-
-            >>> Version('1.0.1-alpha') in Spec('>=1.0.1')
-            False
-            >>> Version('1.0.1-alpha') in Spec('>~1.0.1')
-            True
-
-    .. data:: KIND_NEQ_LOOSE
-
-        The kind of 'Loosely not equal to' specifications::
-
-            >>> Version('1.0.1-alpha') not in Spec('!=1.0.1')
-            False
-            >>> Version('1.0.1-alpha') not in Spec('!~1.0.1')
-            True
 
 
 Combining version specifications (the SpecList class)
@@ -424,21 +400,21 @@ This is possible with the :class:`SpecList` class.
 
     It is build from a comma-separated list of version specifications::
 
-        >>> SpecList('>~1.0.0,<1.2.0,!~1.1.4')
+        >>> SpecList('>=1.0.0,<1.2.0,!=1.1.4')
         <SpecList: (
-            <Spec: >~ <~SemVer: 1 0 0 None None>>,
-            <Spec: < <SemVer: 1 2 0 [] []>>,
-            <Spec: !~ <~SemVer: 1 1 4 None None>>
+            <Spec: >= <~SemVer: 1 0 0 None None>>,
+            <Spec: < <~SemVer: 1 2 0 None None>>,
+            <Spec: != <~SemVer: 1 1 4 None None>>
         )>
 
     Version specifications may also be passed in separated arguments::
 
-        >>> SpecList('>~1.0.0', '<1.2.0', '!~1.1.4,!~1.1.13')
+        >>> SpecList('>=1.0.0', '<1.2.0', '!=1.1.4,!=1.1.13')
         <SpecList: (
-            <Spec: >~ <~SemVer: 1 0 0 None None>>,
-            <Spec: < <SemVer: 1 2 0 [] []>>,
-            <Spec: !~ <~SemVer: 1 1 4 None None>>
-            <Spec: !~ <~SemVer: 1 1 13 None None>>
+            <Spec: >= <~SemVer: 1 0 0 None None>>,
+            <Spec: < <SemVer: 1 2 0 None None>>,
+            <Spec: != <~SemVer: 1 1 4 None None>>
+            <Spec: != <~SemVer: 1 1 13 None None>>
         )>