Fix some documentation TODOs and errata

Readme.rst

@@ -5,8 +5,8 @@ MNMLSTC Core is a small and easy to use C++11 library that adds a functionality
 set that will be available in C++14 and later, as well as some useful
 additions, or some proposals that have not been completely approved yet.
 
-Information on installing and using MNMLSTC Core (as well as modifying its
-internals) can be found in its `documentation <http://mnmlstc.github.io/core>`_
+Information on installing and using MNMLSTC Core can be found in its
+`documentation <http://mnmlstc.github.io/core/>`_.
 
 MNMLSTC Core is released under the Apache 2.0 License.
 

docs/any.rst

@@ -4,6 +4,7 @@ Any Component
 =============
 
 .. default-domain:: cpp
+.. highlight:: cpp
 
 .. |any| replace:: :class:`any`
 
@@ -95,15 +96,36 @@ follow the proposal as closely as possible.
 
 
 
-.. function:: ValueType any_cast (any const&)
-              ValueType any_cast (any&&)
-              ValueType any_cast (any&)
+.. function:: ValueType any_cast (any const& operand)
+              ValueType any_cast (any&& operand)
+              ValueType any_cast (any& operand)
 
-   .. todo:: Discuss behavior and return value.
+   :returns: ``*any_cast<add_const_t<remove_reference_t<ValueType>>(&operand)``
+             for the first :func:`any_cast` signature. For the other overloads,
+             the return type is
+             ``*any_cast<remove_reference_t<ValueType>>(&operand)``.
 
    :raises: :class:`bad_any_cast`
 
-.. function:: ValueType const* any_cast (any const*)
-              ValueType* any_cast (any*)
+   Given a type *ValueType*, it will attempt to extract the value stored within
+   the given |any|. *ValueType* may be either concrete or a reference type.
+   If ``typeid(remove_reference_t<ValueType>)`` is not equal to the value
+   returned by :func:`any::type`, :class:`bad_any_cast` is thrown. Some
+   usage examples::
 
-   .. todo:: Discuss behavior and return value
+      any x(5) // x holds an int
+      auto y = any_cast<int>(x); // cast to a value
+      any_cast<int&>(x) = 10; // cast to a reference for mutation.
+
+      x = std::string { "Woof" }; // x now holds a string.
+      auto woof = std::move(any_cast<std::string&>(x)); // move value in x
+      assert(any_cast<std::string const&>(x) == "");
+
+
+.. function:: ValueType const* any_cast (any const* operand)
+              ValueType* any_cast (any* operand)
+
+   :returns: *ValueType* if operand is not equal to ``nullptr`` and
+             ``typeid(ValueType)`` is the same as the value returned by 
+             :func:`any::type`, a pointer to the object managed by *operand*
+             is returned. Otherwise, ``nullptr``.

docs/expected.rst

@@ -32,8 +32,7 @@ of |expected|.
    contains an optionally instantiated type ``T``. However, unlike
    :class:`optional\<T>`, it is never in a 'null' state. It will instead hold
    an exception that was thrown at some level within the function that returned
-   the |expected|. Additionally, it does not model an object, and
-   only provides :func:`optional\<T>::operator*`.
+   the |expected|. Additionally, it does not model an object.
 
    .. note:: While |expected| uses placement new internally, it
       is ok to use a class that overloads the address-of operator with it.

docs/memory.rst

@@ -6,7 +6,7 @@ Memory Component
 .. default-domain:: cpp
 
 This section discusses the memory component of MNMLSTC Core. Contained in this
-component are two new smart pointers (both with deep copy semantics) and a
+component are three new smart pointers (two with deep copy semantics) and a
 C++11 equivalent to C++14's :func:`make_unique\<T>`.
 
 .. |observer_ptr| replace:: :class:`observer_ptr <observer_ptr\<T>>`
@@ -15,6 +15,9 @@ C++11 equivalent to C++14's :func:`make_unique\<T>`.
 
 .. namespace:: core
 
+Polymorphic Smart Pointer
+-------------------------
+
 .. class:: poly_ptr<T, Deleter>
 
    The |poly_ptr| is a smart pointer for polymorphic types that
@@ -183,6 +186,9 @@ C++11 equivalent to C++14's :func:`make_unique\<T>`.
 
       Swaps the managed object and copier function
 
+Deep Copying Smart Pointer
+--------------------------
+
 .. class:: deep_ptr<T, Deleter, Copier>
 
    |deep_ptr| is a smart pointer for a type that retains sole ownership of the
@@ -321,6 +327,10 @@ C++11 equivalent to C++14's :func:`make_unique\<T>`.
 
       Swaps the managed object, copier object, and deleter object.
 
+
+Dumbest Smart Pointer
+---------------------
+
 .. class:: observer_ptr<T>
 
    |observer_ptr| is "the dumbest smart pointer", in that it is only ever used
@@ -404,6 +414,9 @@ C++11 equivalent to C++14's :func:`make_unique\<T>`.
 
       Resets the object watched by the |observer_ptr| with *ptr*.
 
+Utilities
+---------
+
 .. class:: bad_polymorphic_reset
 
    :inherits: std::logic_error
@@ -456,6 +469,9 @@ C++11 equivalent to C++14's :func:`make_unique\<T>`.
 
    :returns: An empty ``std::unique_ptr<T, D>``
 
+Comparison Operators
+--------------------
+
 .. function:: bool operator == (poly_ptr const&, poly_ptr const&) noexcept
               bool operator != (poly_ptr const&, poly_ptr const&) noexcept
               bool operator >= (poly_ptr const&, poly_ptr const&) noexcept
@@ -526,6 +542,9 @@ C++11 equivalent to C++14's :func:`make_unique\<T>`.
    :returns: The result of comparing the objects watched by |observer_ptr| with
              ``nullptr`` via the given operator
 
+Make Functions
+--------------
+
 .. function:: observer_ptr<T> make_observer(W* ptr)
               observer_ptr<T> make_observer(std::unique_ptr<W, D> const& ptr)
               observer_ptr<T> make_observer(std::shared_ptr<W> const& ptr)

docs/optional.rst

@@ -222,7 +222,30 @@ possible.
               bool operator == (optional<T> const&, T const&) noexcept
               bool operator == (T const&, optional<T> const&) noexcept
 
-   .. todo:: add descriptions of behavior.
+   For the first overload, if only one of the given |optional| values is
+   *engaged*, it will return false. If both |optional| values are 
+   *disengaged*, it will return true. Otherwise the |optional| values compare
+   their managed objects with ``operator ==``
+
+   The second overload returns whether or not the |optional| value is *engaged*.
+   The third overload *always* returns false.
+   The fourth and fifth overloads will check if the |optional| value is
+   *engaged*. If it is, the object managed by |optional| will be compared
+   with ``operator ==``. Otherwise it will return false.
+
+.. function:: bool operator < (optional<T> const&, optional<T> const&) noexcept
+              bool operator < (optional<T> const&, nullopt_t) noexcept
+              bool operator < (nullopt_t, optional<T> const&) noexcept
+              bool operator < (optional<T> const&, T const&) noexcept
+
+   For the first overload, if the right |optional| is *disengaged*, it will
+   return false. If the left |optional| is *disengaged*, it will return true.
+   Otherwise, the result of a comparison ``std::less<T>`` is returned.
+
+   The second overload returns true if the |optional| is *disengaged*.
+   The third overload returns true if the |optional| is *engaged*.
+   The fourth optional returns true if the |optional| is *disengaged*.
+   Otherwise, the result of a comparison with ``std::less<T>`` is returned.
 
 Specializations
 ---------------

docs/variant.rst

@@ -88,7 +88,7 @@ switch statement*
      Visiting a |variant| follows the following semantics. These semantics
      require that, when given a callable type ``Visitor``, and variadic
      arguments ``Args...``, that the return type of the visit will be
-     a  result of ``common_type_t<invoke_of_t<Visitor, Ts, Args...>...>``.
+     a result of ``common_type_t<invoke_of_t<Visitor, Ts, Args...>...>``.
 
      If a common type cannot be found, then the visitation function will
      fail to compile properly. This means that a visitor *must* be capable of
@@ -102,7 +102,9 @@ switch statement*
    .. function:: match (Visitors&&) const
                  match (Visitors&&)
 
-      Takes a variadic number of arguments that are all callable objects.
+      Takes a variadic number of arguments that are all callable objects. These
+      objects are combined into a single visitor and then executed on the
+      |variant|.
 
    .. function:: auto get<N> () noexcept
 
@@ -148,4 +150,5 @@ Specializations
 
    Calls :func:`variant\<Ts>::get`, and returns the value. This specialization
    is provided to interact with ``std::tuple`` and to provide *some* semblance
-   of boost interoperability.
+   of boost interoperability. However it does not support using the type
+   to get the value from the variant.