a few more macros, and put them all in one header

Author: jll63

doc/BOOST_OPENMETHOD_DECLARE_OVERRIDER.adoc

@@ -0,0 +1,52 @@
+
+## BOOST_OPENMETHOD_DECLARE_OVERRIDER
+
+### Synopsis
+
+Defined in <boost/openmethod/macros.hpp>.
+
+```c++
+#define BOOST_OPENMETHOD_DECLARE_OVERRIDER(NAME, (PARAMETERS...), RETURN_TYPE)
+```
+
+### Description
+
+Declares an overrider for a method.
+
+The method is deduced from a call to a method guide function with the
+overrider's arguments.
+
+The macro creates several entities in the current scope.
+
+* A class template that acts as a container for the overriders of the methods
+called `NAME`:
+
+```c++
+template<typename...> BOOST_OPENMETHOD_OVERRIDERS(NAME);
+```
+
+* A specialization of the container template for the overrider:
+
+```c++
+struct BOOST_OPENMETHOD_OVERRIDERS(NAME)<RETURN_TYPE(PARAMETERS...)> {
+    static auto fn(PARAMETERS...) -> RETURN_TYPE;
+    static auto has_next() -> bool;
+    template<typename... Args>
+    static auto next(typename... Args) -> RETURN_TYPE;
+};
+```
+
+where:
+
+* `fn` is the overrider function.
+
+* `has_next()` returns `true` if a less specialized overrider exists.
+
+* `next(Args... args)` calls the next most specialized overrider via the
+pointer stored in the method's `next<fn>` member variable.
+
+`BOOST_OPENMETHOD_DECLARE_OVERRIDER` can be called in a header file, with a
+semicolon after the call. It can be called in a header file, but not multiple
+times in the same translation unit.
+
+NOTE: `NAME` must be an *identifier*. Qualified names are not allowed.

doc/BOOST_OPENMETHOD_DEFINE_OVERRIDER.adoc

@@ -0,0 +1,18 @@
+
+## BOOST_OPENMETHOD_DEFINE_OVERRIDER
+
+### Synopsis
+
+Defined in <boost/openmethod/macros.hpp>.
+
+```c++
+#define BOOST_OPENMETHOD_DEFINE_OVERRIDER(NAME, (PARAMETERS...), RETURN_TYPE)
+```
+
+### Description
+
+Defines the body of an overrider declared with
+`BOOST_OPENMETHOD_DECLARE_OVERRIDER`. It should be called in an implementation
+file, and followed by a function body.
+
+NOTE: `NAME` must be an *identifier*. Qualified names are not allowed.

doc/BOOST_OPENMETHOD_GUIDE.adoc

@@ -0,0 +1,14 @@
+
+## BOOST_OPENMETHOD_GUIDE
+
+### Synopsis
+
+Defined in <boost/openmethod/macros.hpp>.
+
+```c++
+#define BOOST_OPENMETHOD_GUIDE(NAME) /* unspecified */
+```
+
+### Description
+
+Expands to the name of the guide function used to match overriders to methods.

doc/BOOST_OPENMETHOD_NAME.adoc

@@ -5,13 +5,13 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros/name.hpp>.
+Defined in <boost/openmethod/macros.hpp>.
 
 ```c++
-#define BOOST_OPENMETHOD_NAME(NAME) boost_openmethod_#NAME
+#define BOOST_OPENMETHOD_NAME(NAME) /* unspecified */
 ```
 
 ### Description
 
-Generate a long name from a short name, hopefully avoiding conflicts with
-user-defined names.
+Generates a long, obfuscated name from a short name. All the other names
+generated by macros are based on this name.

doc/BOOST_OPENMETHOD_OVERRIDER.adoc

@@ -0,0 +1,15 @@
+
+## BOOST_OPENMETHOD_OVERRIDER
+
+### Synopsis
+
+Defined in <boost/openmethod/macros.hpp>.
+
+```c++
+#define BOOST_OPENMETHOD_OVERRIDER(NAME, (PARAMETERS...), RETURN_TYPE)
+```
+
+### Description
+
+Expands to the specialization of the class template that contains the overrider
+for with the given name, parameter list and return type.

doc/BOOST_OPENMETHOD_REGISTER.adoc

@@ -5,7 +5,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros/register.hpp>.
+Defined in <boost/openmethod/macros.hpp>.
 
 ```c++
 BOOST_OPENMETHOD_REGISTER(TYPE);

doc/headers.adoc

@@ -27,7 +27,8 @@ it is "called" only in a non-evaluated context.
 * It defines an inline function with the same name and signature as the
 method (with the `virtual_` decorators stripped).
 
-Next, let's implement the `Cat` class, in the `felines` namespace:
+Next, let's implement the `Cat` class, and a derived class, `Chhetah`, in the
+`felines` namespace:
 
 [source,c++]
 ----
@@ -40,10 +41,10 @@ include::{examplesdir}/headers_namespaces/cat.cpp[]
 ----
 
 `BOOST_OPENMETHOD_CLASSES` should be placed in an implementation file. It can
-also go in a header file, but this wastes space, as multiple copies of the same
-class data will be created. It doesn't matter which namespace the macro is
-called in. It can take be used with any class name in scope, or with qualified
-names.
+also go in a header file, but this wastes space, as the same registrar will be
+created in every translation unit that includes the header. It doesn't matter
+which namespace the macro is called in. It can take be used with any class name
+in scope, or with qualified names.
 
 `BOOST_OPENMETHOD_OVERRIDE` uses the guide function declared by
 `BOOST_OPENMETHOD` to locate a method that can be called with the same arguments
@@ -63,26 +64,47 @@ struct, it defines the `next` and `has_next` members, and a static function
 called `fn`. The block following the macro is the body of the `fn` function.
 
 It follows that `BOOST_OPENMETHOD_OVERRIDE` should be placed in an
-implementation file.
+implementation file. `BOOST_OPENMETHOD_INLINE_OVERRIDE` works like
+`BOOST_OPENMETHOD_OVERRIDE`, but it defines the `fn` function as inline, so it
+can be used in a header file.
 
-Let's implement the `Dog` class, in the `canines` namespace:
+The overrider for Cats can be accessed in the same translation unit, after it
+has been defined, using the `BOOST_OPENMETHOD_OVERRIDER` macro. It expands to
+the specialization of the overrider container for the overrider's signature. We
+call the static `fn` function to call the overrider.
 
+NOTE: The Cheetah overrider calls the specific overrider for `Cat`, for
+illustration purpose. It is usually better to call `next` instead.
+
+Let's implement the `Dog` class, in the `canines` namespace. This time we want
+the overrider to be accessible in other translation units. We can declare an
+overrider with `BOOST_OPENMETHOD_DECLARE_OVERRIDER`, without actually defining
+the static function `fn` just yet.
 
 [source,c++]
 ----
 include::{examplesdir}/headers_namespaces/dog.hpp[]
 ----
 
+Unlike function declarations, which can occur multiple times in a TU, an
+overrider declaration cannot. For example, this is illegal:
+
+```c++
+BOOST_OPENMETHOD_DECLARE_OVERRIDER(
+    poke, (std::ostream&, virtual_ptr<Dog>), void);
+
+BOOST_OPENMETHOD_DECLARE_OVERRIDER(
+    poke, (std::ostream&, virtual_ptr<Dog>), void);
+```
+
+Now we use `BOOST_OPENMETHOD_DEFINE_OVERRIDER` to define the overrider:
+
 [source,c++]
 ----
 include::{examplesdir}/headers_namespaces/dog.cpp[]
 ----
 
-`BOOST_OPENMETHOD_INLINE_OVERRIDE` works like `BOOST_OPENMETHOD_OVERRIDE`, but
-it can be used in a header file, because it defines the `fn` function inline.
-
-
-Let's look at the main program now. It derived `Bullgod` from `Dog` and provides
+Let's look at the main program now. It derived `Bulldog` from `Dog` and provides
 an overrider for the new class:
 
 [source,c++]
@@ -154,12 +176,12 @@ BOOST_OPENMETHOD_OVERRIDE(
 ```
 
 But `BOOST_OPENMETHOD_OVERRIDE` also uses the name to derive the overrider
-container's name, using preprocessor token pasting. And the result will be an
-invalid declaration.
+container's name, using preprocessor token pasting, resulting in an invalid
+declaration error.
 
-All we need to do is to make `BOOST_OPENMETHOD_OVERRIDE` "see" the guide
-function. Its name is produced by macro `BOOST_OPENMETHOD_GUIDE(NAME)`. Thus we
-can use a using-declaration to bring the guide function into the current scope:
+We need to do is to make `BOOST_OPENMETHOD_OVERRIDE` "see" the guide function.
+Its name is returned by macro `BOOST_OPENMETHOD_GUIDE(NAME)`. We can use a
+using-declaration to bring the guide function into the current scope:
 
 ```c++
 using app_specific_behavior::BOOST_OPENMETHOD_GUIDE(meet);

doc/headers_namespaces.adoc

@@ -9,13 +9,17 @@ include::overview.adoc[]
 include::BOOST_OPENMETHOD.adoc[]
 include::BOOST_OPENMETHOD_OVERRIDE.adoc[]
 include::BOOST_OPENMETHOD_INLINE_OVERRIDE.adoc[]
+include::BOOST_OPENMETHOD_DECLARE_OVERRIDER.adoc[]
+include::BOOST_OPENMETHOD_DEFINE_OVERRIDER.adoc[]
+include::BOOST_OPENMETHOD_OVERRIDER.adoc[]
+include::BOOST_OPENMETHOD_NAME.adoc[]
+include::BOOST_OPENMETHOD_GUIDE.adoc[]
+include::BOOST_OPENMETHOD_OVERRIDERS.adoc[]
 include::BOOST_OPENMETHOD_REGISTER.adoc[]
 include::BOOST_OPENMETHOD_CLASSES.adoc[]
 include::BOOST_OPENMETHOD_DEFAULT_POLICY.adoc[]
-include::BOOST_OPENMETHOD_NAME.adoc[]
-include::BOOST_OPENMETHOD_OVERRIDERS.adoc[]
-include::initialize.adoc[]
 
+include::initialize.adoc[]
 include::typedefs.adoc[]
 include::method.adoc[]
 include::method_override.adoc[]
@@ -24,7 +28,6 @@ include::virtual_traits.adoc[]
 include::use_classes.adoc[]
 include::virtual_.adoc[]
 include::with_vptr.adoc[]
-
 include::abstract_policy.adoc[]
 include::domain.adoc[]
 include::basic_policy.adoc[]

doc/reference.adoc

@@ -22,7 +22,7 @@ using namespace boost::openmethod;
 
 // tag::method[]
 
-#include <boost/openmethod/macros/name.hpp>
+#include <boost/openmethod/macros.hpp>
 
 class BOOST_OPENMETHOD_NAME(poke);
 
@@ -39,7 +39,7 @@ static poke::override<poke_cat> override_poke_cat;
 // end::poke_cat[]
 
 // tag::poke_dog[]
-#include <boost/openmethod/macros/register.hpp>
+#include <boost/openmethod/macros.hpp>
 
 auto poke_dog(std::ostream& os, virtual_ptr<Dog> dog) {
     os << "bark";