From 17b5aca0e087820cf0545ac6923242676dd042d6 Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@gmail.com>
Date: Sun, 29 Dec 2019 23:55:50 +0100
Subject: doc: document header derivable.hpp

---
 doc/src/conf.py               |  2 ++
 doc/src/index.rst             | 48 +++++++++++++++++++++++++++++++++++++++++--
 include/newtype/derivable.hpp |  5 +++--
 3 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/doc/src/conf.py b/doc/src/conf.py
index 230960d..437d275 100644
--- a/doc/src/conf.py
+++ b/doc/src/conf.py
@@ -27,6 +27,8 @@ pygments_style = 'tango'
 
 exclude_patterns = []
 
+numfig = True
+
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = 'haiku'
diff --git a/doc/src/index.rst b/doc/src/index.rst
index af0e2c9..62e41f2 100644
--- a/doc/src/index.rst
+++ b/doc/src/index.rst
@@ -50,7 +50,7 @@ API
 
 This section of the documentation describes the public API of the *new_type*.
 It provides detailed descriptions of the types and functions designed to be used by applications.
-Additionally, this section provides usage examples that demonstrate the use and properties of the public API.
+All declarations described in this section are found in the namespace :cpp:any:`nt`, unless noted otherwise.
 
 Header :literal:`<newtype/new_type.hpp>`
 ========================================
@@ -249,7 +249,51 @@ Stream I/O Operators
 
    **noexcept specification:** This input operator shall be noexcept iff. :cpp:type:`new_type<BaseType, TagType, DerivationClause>::base_type` is nothrow input streamable.
 
-   **enablement:** This operator shall be available iff. a) :cpp:type:`new_type<BaseType, TagType, DerivationClause>::base_type` supports being read from a stream using the operator :literal:`>>` and b) :cpp:type:`DerivationClause` includes :cpp:var:`Reads`.
+   **enablement:** This operator shall be available iff. a) :cpp:type:`new_type<BaseType, TagType, DerivationClause>::base_type` supports being read from a stream using the operator :literal:`>>` and b) :cpp:type:`DerivationClause` includes :cpp:var:`Read`.
+
+Header :literal:`<newtype/derivable.hpp>`
+=========================================
+
+This header defines the alias template :cpp:type:`derivable` as well as the set of standard derivation tags.
+
+Alias template :cpp:type:`derivable`
+------------------------------------
+
+.. cpp:type:: template<typename NameTag> \
+              derivable = type<NameTag>
+
+Standard derivation tags
+------------------------
+
+.. cpp:var:: auto constexpr Arithmetic = derivable<struct arithmetic_tag>{}
+
+   This tag enables the derivation of the arithmetic operators :cpp:func:`operator+`, :cpp:func:`operator-`, :cpp:func:`operator*`, :cpp:func:`operator/`, :cpp:func:`operator+=`, :cpp:func:`operator-=`, :cpp:func:`operator*=`, and :cpp:func:`operator/=`
+
+.. cpp:var:: auto constexpr EqBase = derivable<struct eq_base_tag>{}
+
+   This tag enables the derivation of "Equality comparison with base type" operators :literal:`==` and :literal:`!=`
+   By virtue of its nature, deriving this feature compromises the strength of the given :cpp:class:`new_type`.
+
+.. cpp:var:: auto constexpr ImplicitConversion = derivable<struct implicit_conversion_tag>{}
+
+   This tag enables the derivation of the implicit "conversion to base type" operator.
+   By virtue of its nature, deriving this feature compromises the strength of the given :cpp:class:`new_type`.
+
+.. cpp:var:: auto constexpr Indirection = derivable<struct indirection_tag>{}
+
+   This tag enables the derivation of the "member access through pointer" operators :cpp:func:`new_type::operator->`
+
+.. cpp:var:: auto constexpr Read = derivable<struct read_tag>{}
+
+   This tag enables the derivation of the "stream output" operator :cpp:func:`operator<<`
+
+.. cpp:var:: auto constexpr Relational = derivable<struct relational_tag>{}
+
+   This tag enables the derivation of the relational operators :cpp:func:`operator<`, :cpp:func:`operator>`, :cpp:func:`operator<=`, and :cpp:func:`operator>=`
+
+.. cpp:var:: auto constexpr Show = derivable<struct show_tag>{}
+
+   This tag enables the derivation of the "stream input" operator :cpp:func:`operator>>`
 
 Header :literal:`<newtype/derivation_clause.hpp>`
 =================================================
diff --git a/include/newtype/derivable.hpp b/include/newtype/derivable.hpp
index 1b6651f..d5672ac 100644
--- a/include/newtype/derivable.hpp
+++ b/include/newtype/derivable.hpp
@@ -27,11 +27,12 @@ namespace nt
     auto constexpr Arithmetic = derivable<struct arithmetic_tag>{};
 
     /**
-     * @brief A tag to enable derivation of equality comparison operators
+     * @brief A tag to enable derivation of "equality comparison with base type" operators
      *
+     * @note Deriving this feature seriously weakens the using nt::new_type instance
      * @since 1.0.0
      */
-    auto constexpr EqBase = derivable<struct eq_tag>{};
+    auto constexpr EqBase = derivable<struct eq_base_tag>{};
 
     /**
      * @brief A tag to enable derivation of the implicit "conversion to base type" operator
-- 
cgit v1.2.3