doc: add section with version-checking macros and functions

3 files changed, 61 insertions, 11 deletions

diff --git a/docs/src/index.rst b/docs/src/index.rst
index 9cdc494a..fa89c4bf 100644
--- a/docs/src/index.rst
+++ b/docs/src/index.rst
@@ -68,6 +68,7 @@ Documentation
 
    design
    errors
+   version
    loop
    handle
    request
diff --git a/docs/src/misc.rst b/docs/src/misc.rst
index 9708c5de..e9ddba3d 100644
--- a/docs/src/misc.rst
+++ b/docs/src/misc.rst
@@ -135,17 +135,6 @@ API
     For :man:`isatty(3)` equivalent functionality use this function and test
     for ``UV_TTY``.
 
-.. c:function:: unsigned int uv_version(void)
-
-    Returns the libuv version packed into a single integer. 8 bits are used for
-    each component, with the patch number stored in the 8 least significant
-    bits. E.g. for libuv 1.2.3 this would return 0x010203.
-
-.. c:function:: const char* uv_version_string(void)
-
-    Returns the libuv version number as a string. For non-release versions
-    "-pre" is appended, so the version number could be "1.2.3-pre".
-
 .. c:function:: int uv_replace_allocator(uv_malloc_func malloc_func, uv_realloc_func realloc_func, uv_calloc_func calloc_func, uv_free_func free_func)
 
     .. versionadded:: 1.6.0
diff --git a/docs/src/version.rst b/docs/src/version.rst
new file mode 100644
index 00000000..e1715b2d
--- /dev/null
+++ b/docs/src/version.rst
@@ -0,0 +1,60 @@
+
+.. _version:
+
+Version-checking macros and functions
+=====================================
+
+Starting with version 1.0.0 libuv follows the `semantic versioning`_
+scheme. This means that new APIs can be introduced throughout the lifetime of
+a major release. In this section you'll find all macros and functions that
+will allow you to write or compile code conditionally, in order to work with
+multiple libuv versions.
+
+.. _semantic versioning: http://semver.org
+
+
+Macros
+------
+
+.. c:macro:: UV_VERSION_MAJOR
+
+    libuv version's major number.
+
+.. c:macro:: UV_VERSION_MINOR
+
+    libuv version's minor number.
+
+.. c:macro:: UV_VERSION_PATCH
+
+    libuv version's patch number.
+
+.. c:macro:: UV_VERSION_IS_RELEASE
+
+    Set to 1 to indicate a release version of libuv, 0 for a development
+    snapshot.
+
+.. c:macro:: UV_VERSION_SUFFIX
+
+    libuv version suffix. Certain development releases such as Release Candidates
+    might have a suffix such as "rc".
+
+.. c:macro:: UV_VERSION_HEX
+
+    Returns the libuv version packed into a single integer. 8 bits are used for
+    each component, with the patch number stored in the 8 least significant
+    bits. E.g. for libuv 1.2.3 this would be 0x010203.
+
+    .. versionadded:: 1.7.0
+
+
+Functions
+---------
+
+.. c:function:: unsigned int uv_version(void)
+
+    Returns :c:macro:`UV_VERSION_HEX`.
+
+.. c:function:: const char* uv_version_string(void)
+
+    Returns the libuv version number as a string. For non-release versions the
+    version suffix is included.