Started documenting the user_defined_typeinfo example and embedding it into the docs

doc/type_index.qbk

@@ -202,6 +202,15 @@ expands to nothing.
 
 [xinclude autodoc.xml]
 
+[section Making own type_index]
+[import ../examples/user_defined_typeinfo.cpp]
+[type_index_userdefined_usertypes]
+[type_index_userdefined_enum]
+[type_index_my_type_index]
+[type_index_my_type_index_usage]
+[endsect]
+
+
 [section Space and Performance]
 
 * `ctti_type_info` uses macro for getting full text representation of function name which could lead to code bloat,

examples/user_defined_typeinfo.cpp

@@ -4,13 +4,14 @@
 // (See the accompanying file LICENSE_1_0.txt
 // or a copy at <http://www.boost.org/LICENSE_1_0.txt>.)
 
-//[type_index_userdefined
+//[type_index_userdefined_usertypes
 /*`
     The following example shows how a user defined type_info can be created and used.
     Example works with and without RTTI.
+
+    Consider situation when user uses only those types in `typeid()`:
 */
 
-#include <boost/type_index/type_index_facade.hpp>
 #include <vector>
 #include <string>
 
@@ -22,8 +23,20 @@ struct my_struct;
 typedef std::vector<my_class> my_classes;
 typedef std::string my_string;
 
+} // namespace my_namespace
 
-namespace detail {
+//] [/type_index_userdefined_usertypes]
+
+
+//[type_index_userdefined_enum
+/*`
+    In that case user may wish to save space in binary and create it's own type system.
+    For that case `detail::typenum<>` meta function is added. Depending on the input type T
+    this function will return different numeric values.
+*/
+#include <boost/type_index/type_index_facade.hpp>
+
+namespace my_namespace { namespace detail {
     template <class T> struct typenum;
     template <> struct typenum<void>{       enum {value = 0}; };
     template <> struct typenum<my_class>{   enum {value = 1}; };
@@ -31,7 +44,10 @@ namespace detail {
     template <> struct typenum<my_classes>{ enum {value = 3}; };
     template <> struct typenum<my_string>{  enum {value = 4}; };
 
+    // my_typeinfo structure is used to save type number
     struct my_typeinfo {
+        // type_[0] will hold a type number
+        // type_[1] will be '\0', to have a zero terminated raw type name
         char type_[2];
     };
 
@@ -40,7 +56,20 @@ namespace detail {
         static const my_typeinfo ret = {{ static_cast<char>(typenum<T>::value), '\0' }};
         return ret;
     }
-}
+}} // my_namespace::detail
+
+//] [/type_index_userdefined_usertypes]
+
+
+//[type_index_my_type_index
+/*`
+    `my_type_index` is a user created type_index class. If in doubt during this phase, you can always 
+    take a look at the `<boost/type_index/ctti_type_index.hpp>` or `<boost/type_index/stl_type_index.hpp>`
+    files. Documentation for `type_index_facade` could be also useful.
+
+    See implementation of `my_type_index`:
+*/
+namespace my_namespace {
 
 class my_type_index: public boost::typeind::type_index_facade<my_type_index, detail::my_typeinfo> {
     const detail::my_typeinfo* data_;
@@ -80,11 +109,27 @@ public:
     }
 };
 
+} // namespace my_namespace
+
+/*`
+    Note that we have used the boost::typeind::type_index_facade class as base.
+    That class took care about all the helper function and operators (comparison, hashing, ostreaming and others).
+*/
+
+//] [/type_index_my_type_index]
+
+namespace my_namespace {
+
 class my_class{};
 struct my_struct{};
 
 } // namespace my_namespace
 
+//[type_index_my_type_index_usage
+/*`
+    Finally we can use the my_type_index class for getting type indexes:
+*/
+
 using namespace my_namespace;
 #include <cassert>
 
@@ -102,4 +147,5 @@ int main() {
     assert(cl1.pretty_name() == "my_class");
 }
 
-//] [/type_index_userdefined]
+//] [/type_index_my_type_index_usage]
+