doc

CMakeLists.txt

@@ -62,19 +62,7 @@ endif()
 option(YOMM2_ENABLE_DOC "Set to ON to generate tutorials and reference" OFF)
 option(YOMM2_ENABLE_BENCHMARKS "Set to ON to enable benchmarks" OFF)
 
-set(readme_md "${CMAKE_SOURCE_DIR}/docs/README.md")
-set(readme_cpp "${CMAKE_SOURCE_DIR}/docs.in/README.cpp")
-
-if(${YOMM2_ENABLE_DOC})
-  message(STATUS "Documentation generation enabled")
-  add_custom_target(README ALL DEPENDS "${readme_md}")
-  add_custom_command(
-    OUTPUT "${readme_md}"
-    COMMAND ${CMAKE_SOURCE_DIR}/dev/code2md "${readme_cpp}" "${readme_md}"
-    DEPENDS "${readme_cpp}")
-endif()
-
-add_subdirectory(docs.in/reference)
+add_subdirectory(docs.in)
 
 ## Install instruction
 # Create version file for cmake package

docs.in/README.cpp

@@ -21,7 +21,7 @@
 // If you are familiar with the concept of open multi-methods, or if you prefer
 // to learn by reading code, go directly to [the
 // synopsis](examples/synopsis.cpp). The [reference is
-// here](reference/reference.md)
+// here](reference/README.md)
 
 // ## Open Methods in a Nutshell
 

docs.in/reference/CMakeLists.txt

@@ -3,45 +3,4 @@
 # See accompanying file LICENSE_1_0.txt
 # or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-file(GLOB cpps "*.cpp")
-
-set(code_deps "${CMAKE_SOURCE_DIR}/dev/code2md;${CMAKE_SOURCE_DIR}/dev/md2md;${CMAKE_SOURCE_DIR}/dev/mdgen.py")
-set(entries "")
-
-foreach(cpp ${cpps})
-    cmake_path(REMOVE_EXTENSION cpp LAST_ONLY OUTPUT_VARIABLE md)
-
-    if(${YOMM2_ENABLE_DOC})
-        set(md "${md}.md")
-        string(REPLACE "docs.in" "docs" md_out "${md}")
-        add_custom_command(
-            OUTPUT "${md_out}"
-            COMMAND ${CMAKE_SOURCE_DIR}/dev/code2md "${cpp}" "${md_out}"
-            DEPENDS "${cpp};${code_deps}")
-        list(APPEND entries "${md_out}")
-    endif()
-
-    cmake_path(GET cpp STEM exe)
-    set(exe "ref_${exe}")
-    add_executable("${exe}" "${cpp}")
-    add_compile_definitions(YOMM2_CODE)
-    target_link_libraries("${exe}" YOMM2::yomm2)
-    add_test(NAME "${exe}" COMMAND "${exe}")
-endforeach()
-
-if(${YOMM2_ENABLE_DOC})
-    file(GLOB_RECURSE MDs "*.md")
-    message(STATUS "${MDs}")
-
-    foreach(MD ${MDs})
-        string(REPLACE "docs.in" "docs" MD_out "${MD}")
-        add_custom_command(
-            OUTPUT "${MD_out}"
-            COMMAND ${CMAKE_SOURCE_DIR}/dev/md2md "${MD}" "${MD_out}"
-            DEPENDS "${MD};${code_deps}")
-        list(APPEND entries "${MD_out}")
-        message(STATUS "${MD_out}")
-        endforeach()
-
-    add_custom_target(reference ALL DEPENDS "${entries}")
-endif()
+generate_doc()

docs/README.md

@@ -21,7 +21,7 @@ Stroustrup.
 If you are familiar with the concept of open multi-methods, or if you prefer
 to learn by reading code, go directly to [the
 synopsis](examples/synopsis.cpp). The [reference is
-here](reference/reference.md)
+here](reference/README.md)
 
 ## Open Methods in a Nutshell
 

docs/reference/RestrictedOutputStream.md

@@ -0,0 +1,7 @@
+<sub>[home](/README.md) / [docs](/docs.md) / [reference](/docs/reference.md)</sub><br>
+
+    Stream& operator<<(Stream& os, const std::string_view& view);
+    Stream& operator<<(Stream& os, const void* value);
+    Stream& operator<<(Stream& os, size_t value);
+
+(where `Stream` is the type of the `error_stream` data member)

docs/reference/YOMM2_GENSYM.md

@@ -0,0 +1,19 @@
+<sub>/ [home](/README.md) / [reference](/docs/reference/README.md) </sub>
+
+**YOMM2_GENSYM**<br>
+<sub>defined in <yorel/yomm2/symbols.hpp>, also provided by<yorel/yomm2/keywords.hpp></sub>
+
+---
+`YOMM2_GENSYM` expands to a new C++ identifier each time it is called. The
+symbol is based on the `__COUNTER__` preprocessor macro, and decorated in such a
+way that it is unlikely to clash with user-defined symbols.
+
+`YOMM2_GENSYM` provides a convenient way of allocating [static
+objects](static-object.md) for registering classes, methods, or definitions.
+
+### example
+
+```c++
+int YOMM2_GENSYM;
+int YOMM2_GENSYM; // not a redefinition, this is a new symbol
+```

docs/reference/YOMM2_STATIC.md

@@ -0,0 +1,18 @@
+<sub>[home](/README.md) / [docs](/docs.md) / [reference](/docs/reference.md)</sub><br>
+# YOMM2_STATIC
+<sub>defined in <yorel/yomm2/symbols.hpp>, also provided by<yorel/yomm2/keywords.hpp></sub>
+
+```c++
+#define YOMM2_STATIC(...) static __VA_ARGS__ YOMM2_GENSYM
+```
+
+`YOMM2_STATIC` provides a convenient way to create a static object just for
+executing its constructor at static initialization time. The macro creates an
+obfuscated name for the object, which is unlikely to clash with any other name.
+
+### Example
+
+```c++
+// Instantiate a 'use_classes' object to register three classes.
+YOMM2_STATIC(yorel::yomm2::use_classes<Animal, Cat, Dog>);
+```

docs/reference/YOMM2_SYMBOL.md

@@ -0,0 +1,29 @@
+
+
+<sub>/ [home](/README.md) / [reference](/docs/reference/README.md) </sub>
+
+**YOMM2_SYMBOL**<br>
+<sub>defined in <yorel/yomm2/symbols.hpp>, also provided by<yorel/yomm2/keywords.hpp></sub>
+
+---
+```
+#define YOMM2_SYMBOL(seed) /*unspecified*/
+```
+---
+Macro `YOMM2_SYMBOL` expands to an obfuscated symbol, unlikely
+to clash with other names in scope.
+
+
+## example
+
+
+```c++
+#include <yorel/yomm2/symbols.hpp>
+
+BOOST_AUTO_TEST_CASE(ref_example) {
+    int foo = 1;
+    int YOMM2_SYMBOL(foo) = 2;
+    BOOST_TEST(foo == 1);
+    BOOST_TEST(YOMM2_SYMBOL(foo) == 2);
+}
+```

docs/reference/aggregate.md

@@ -0,0 +1,41 @@
+
+
+<sub>/ [home](/README.md) / [reference](/docs/reference/README.md) </sub>
+
+**yorel::yomm2::aggregate**<br>
+<sub>defined in <yorel/yomm2/core.hpp>, also provided by<yorel/yomm2/keywords.hpp></sub>
+
+---
+```
+template<typename... T> struct aggregate;
+```
+---
+An instance of `aggregate<T...>` contains one `T` sub-object for each
+specified `T`, just like a `std::tuple`.
+`aggregate` provides a convenient way to instantiate a collection of [YOMM2
+registration objects](static-object.md). Typically, the name of the variable
+does not matter, and [YOMM2_GENSYM](/docs/reference/YOMM2_GENSYM.md) can be used to generated that single-use
+identifier.
+Unlike typical `std::tuple<typename... T>` implementations, `aggregate` can
+handle large numbers of `T`s. For example, clang++-12 has a limit of 1024
+types, which can be reached easily when writing templatized method
+definitions.
+## example
+
+
+```c++
+#include <yorel/yomm2/keywords.hpp>
+#include <yorel/yomm2/templates.hpp>
+
+using namespace yorel::yomm2;
+
+struct Animal { virtual ~Animal() {} };
+struct Dog : Animal {};
+struct Cat : Animal {};
+
+aggregate<
+    class_declaration<types<Animal>>,
+    class_declaration<types<Dog, Animal>>,
+    class_declaration<types<Cat, Animal>>
+> YOMM2_GENSYM;
+```

docs/reference/apply_product.md

@@ -0,0 +1,52 @@
+
+
+<sub>/ [home](/README.md) / [reference](/docs/reference/README.md) </sub>
+
+**yorel::yomm2::apply_product** <small>(experimental)</small><br>
+<sub>defined in <yorel/yomm2/templates.hpp></sub>
+
+---
+```
+template<typename TemplateList, typename... TypeLists>
+using apply_product = /*unspecified*/;
+```
+---
+`apply_product` takes a [templates](/docs/reference/templates.md) list and list of [types](/docs/reference/types.md) lists, and
+evaluates to a `types` list consisting of the application of each template to
+the n-fold Cartesian product of the input `types` lists.
+
+## example
+
+
+```c++
+#include <type_traits>
+#include <yorel/yomm2/core.hpp>
+#include <yorel/yomm2/templates.hpp>
+
+using namespace yorel::yomm2;
+
+struct a;
+struct b;
+struct x;
+struct y;
+struct z;
+
+template<typename, typename> struct bin1;
+template<typename, typename> struct bin2;
+
+static_assert(
+    std::is_same_v<
+        apply_product<
+            templates<bin1, bin2>,
+            types<a, b>, 
+            types<x, y, z> 
+        >,
+        types<
+            bin1<a, x>, bin1<a, y>, bin1<a, z>,
+            bin1<b, x>, bin1<b, y>, bin1<b, z>,
+
+            bin2<a, x>, bin2<a, y>, bin2<a, z>,
+            bin2<b, x>, bin2<b, y>, bin2<b, z>
+        >
+    >);
+```

docs/reference/basic_error_output.md

@@ -0,0 +1,39 @@
+<sub>[home](/README.md) / [docs](/docs.md) / [reference](/docs/reference.md)</sub><br>
+# yorel::yomm2::policy::**basic_error_output**
+<sub>defined in <yorel/yomm2/policy.hpp>, also provided by<yorel/yomm2/core.hpp>, <yorel/yomm2/keywords.hpp></sub>
+
+    template<class Policy, typename Stream = /*unspecified*/>
+    struct basic_error_output;
+
+`basic_error_output` implements the `error_output` facet.
+
+## Template parameters
+
+| Name                        | Value                               |
+| --------------------------- | ----------------------------------- |
+| class [**Policy**](#policy) | the policy containing the facet     |
+| class [**Stream**](#stream) | a model of `RestrictedOutputStream` |
+
+### Policy
+
+The policy containing the facet. Since `basic_error_output` has static state,
+making the policy a template parameter ensures that each policy has its own set
+of static member variables.
+
+### Stream
+
+`Stream` can be any type that satisfies the requirements of
+[`RestrictedOutputStream`](/docs/reference/RestrictedOutputStream.md). The default value is a lightweight version of
+`std::ostream` that writes to `stderr`, using low-level C functions.
+
+## Static member variables
+
+| Name                                     | Value                   |
+| ---------------------------------------- | ----------------------- |
+| Stream [**error_stream**](error_stream)  | the stream to print to  |
+
+### yorel::yomm2::policy::**error_stream**
+
+Initialized by the default constructor of `Stream`. It is the responsibility of
+the program to perform further initialization if needed - for example, open a
+`std::ofstream`, before calling `update`.

docs/reference/basic_trace_output.md

@@ -0,0 +1,47 @@
+<sub>[home](/README.md) / [docs](/docs.md) / [reference](/docs/reference.md)</sub><br>
+# yorel::yomm2::policy::**basic_trace_output**
+<sub>defined in <yorel/yomm2/policy.hpp>, also provided by<yorel/yomm2/core.hpp>, <yorel/yomm2/keywords.hpp></sub>
+
+    template<class Policy, typename Stream = /*unspecified*/>
+    struct basic_trace_output;
+
+`basic_trace_output` implements the `trace_output` facet.
+
+## Template parameters
+
+| Name                        | Value                               |
+| --------------------------- | ----------------------------------- |
+| class [**Policy**](#policy) | the policy containing the facet     |
+| class [**Stream**](#stream) | a model of `RestrictedOutputStream` |
+
+### Policy
+
+The policy containing the facet. Since `basic_trace_output` has static state,
+making the policy a template parameter ensures that each policy has its own set
+of static member variables.
+
+### Stream
+
+`Stream` can be any type that satisfies the requirements of
+[`RestrictedOutputStream`](/docs/reference/RestrictedOutputStream.md). The default value is a lightweight version of
+`std::ostream` that writes to `stderr`, using low-level C functions.
+
+## Static member variables
+
+| Name                                     | Value                   |
+| ---------------------------------------- | ----------------------- |
+| bool [**trace_enabled**](#trace_enabled) | enable or disable trace |
+| Stream [**trace_stream**](trace_stream)  | the stream to print to  |
+
+### yorel::yomm2::policy::**trace_enabled**
+
+Controls whether information is printed to `trace_stream`. The flag is
+initialized by examining the `YOMM2_TRACE` environment variable. If it is set,
+and its value is `1`, trace is enabled. Other values are reserved for possible
+future use.
+
+### yorel::yomm2::policy::**trace_stream**
+
+Initialized by the default constructor of `Stream`. It is the responsibility of
+the program to perform further initialization if needed - for example, open a
+`std::ofstream`, before calling `update`.