Documented a couple more macros

git-svn-id: https://svn.cct.lsu.edu/repos/projects/parallex/trunk/hpx@8144 5079c8e4-9419-0410-93bb-9e5ee278c886

CMakeLists.txt

@@ -1228,7 +1228,9 @@ if(DOXYGEN_FOUND)
       "${hpx_SOURCE_DIR}/hpx/hpx_fwd.hpp"
       "${hpx_SOURCE_DIR}/hpx/hpx_init.hpp"
       "${hpx_SOURCE_DIR}/hpx/exception.hpp"
-      "${hpx_SOURCE_DIR}/hpx/runtime/actions/plain_action.hpp")
+      "${hpx_SOURCE_DIR}/hpx/runtime/actions/action_support.hpp"
+      "${hpx_SOURCE_DIR}/hpx/runtime/actions/plain_action.hpp"
+      "${hpx_SOURCE_DIR}/hpx/runtime/actions/component_action.hpp")
 
   foreach(doxygen_input ${doxygen_inputs_list})
     set(doxygen_inputs "${doxygen_inputs} ${doxygen_input}")

docs/CMakeLists.txt

@@ -34,7 +34,9 @@ if(DOXYGEN_FOUND)
       ${hpx_SOURCE_DIR}/hpx/hpx_fwd.hpp
       ${hpx_SOURCE_DIR}/hpx/hpx_init.hpp
       ${hpx_SOURCE_DIR}/hpx/exception.hpp
-      ${hpx_SOURCE_DIR}/hpx/runtime/actions/plain_action.hpp)
+      ${hpx_SOURCE_DIR}/hpx/runtime/actions/action_support.hpp 
+      ${hpx_SOURCE_DIR}/hpx/runtime/actions/plain_action.hpp
+      ${hpx_SOURCE_DIR}/hpx/runtime/actions/component_action.hpp)
 
   # Generate Doxygen from the source code.
   hpx_source_to_boostbook(hpx_autodoc

docs/manual/applying_actions.qbk

@@ -97,14 +97,13 @@ demonstrating this. The first snippet has to go into the header file:
 
     // Note: The second arguments to the macro below have to be systemwide-unique
     //       C++ identifiers
-    ``[macroref HPX_REGISTER_ACTION_DECLARATION_EX `HPX_REGISTER_ACTION_DECLARATION_EX`]``(app::some_component::some_member_action,
-        app_some_member_action);
+    ``[macroref HPX_REGISTER_ACTION_DECLARATION `HPX_REGISTER_ACTION_DECLARATION`]``(app::some_component::some_member_action);
 
 The next snippet belongs into the source file:
 
     // The parameters for this macro have to be the same as used in the corresponding
-    // HPX_REGISTER_ACTION_DECLARATION_EX() macro invocation above
-    ``[macroref HPX_REGISTER_ACTION_EX `HPX_REGISTER_ACTION_EX`]``(app::some_component::some_member_action, app_some_member_action);
+    // HPX_REGISTER_ACTION_DECLARATION() macro invocation above
+    ``[macroref HPX_REGISTER_ACTION `HPX_REGISTER_ACTION`]``(app::some_component::some_member_action);
 
 Granted, these macro invocations are a bit more complex than for simple global
 functions, however we believe they are still manageable.

hpx/runtime/actions/action_support.hpp

@@ -5,6 +5,8 @@
 //  Distributed under the Boost Software License, Version 1.0. (See accompanying
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+/// \file action_support.hpp
+
 #if !defined(HPX_RUNTIME_ACTIONS_ACTION_SUPPORT_NOV_14_2008_0711PM)
 #define HPX_RUNTIME_ACTIONS_ACTION_SUPPORT_NOV_14_2008_0711PM
 
@@ -54,6 +56,8 @@
 ///////////////////////////////////////////////////////////////////////////////
 namespace hpx { namespace actions
 {
+    /// \cond NOINTERNAL
+
     ///////////////////////////////////////////////////////////////////////////
     namespace detail
     {
@@ -700,8 +704,12 @@ namespace hpx { namespace actions
           : boost::mpl::if_<boost::is_same<Derived, this_type>, Action, Derived>
         {};
     }
+
+    /// \endcond
 }}
 
+/// \cond NOINTERNAL
+
 #include <hpx/config/warnings_suffix.hpp>
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -735,8 +743,6 @@ namespace hpx { namespace actions
                 _##actionname);                                               \
     /**/
 
-#define HPX_REGISTER_ACTION(action) HPX_REGISTER_ACTION_EX(action, action)
-
 #define HPX_REGISTER_ACTION_DECLARATION_NO_DEFAULT_GUID1(action)              \
     namespace hpx { namespace actions { namespace detail {                    \
         template <> HPX_ALWAYS_EXPORT                                         \
@@ -767,9 +773,70 @@ namespace hpx { namespace actions
         BOOST_PP_STRINGIZE(actionname))                                       \
     HPX_REGISTER_ACTION_DECLARATION_GUID(hpx::actions::transfer_action<action>) \
 /**/
+
+/// \endcond
+
+/// \def HPX_REGISTER_ACTION_DECLARATION(action)
+///
+/// \brief Declare the necessary component action boilerplate code.
+///
+/// The macro \a HPX_REGISTER_ACTION_DECLARATION can be used to declare all the
+/// boilerplate code which is required for proper functioning of component
+/// actions in the context of HPX.
+///
+/// The parameter \a action is the type of the action to declare the
+/// boilerplate for.
+///
+/// \par Example:
+///
+/// \code
+///      namespace app
+///      {
+///          // Define a simple component exposing one action 'print_greating'
+///          class HPX_COMPONENT_EXPORT server
+///            : public hpx::components::simple_component_base<server>
+///          {
+///              void print_greating ()
+///              {
+///                  hpx::cout << "Hey, how are you?\n" << hpx::flush;
+///              }
+///
+///              // Component actions need to be declared, this also defines the
+///              // type 'print_greating_action' representing the action.
+///              HPX_DEFINE_COMPONENT_ACTION(server, print_greating, print_greating_action);
+///          };
+///      }
+///
+///      // Declare boilerplate code required for each of the component actions.
+///      HPX_REGISTER_ACTION_DECLARATION(app::server::print_greating_action);
+/// \endcode
+///
+/// \note This macro has to be used once for each of the component actions
+/// defined using one of the \a HPX_DEFINE_COMPONENT_ACTION macros. It has to
+/// be visible in all translation units using the action, thus it is
+/// recommended to place it into the header file defining the component.
 #define HPX_REGISTER_ACTION_DECLARATION(action)                               \
     HPX_REGISTER_ACTION_DECLARATION_EX(action, action)                        \
 /**/
 
+/// \def HPX_REGISTER_ACTION(action)
+///
+/// \brief Define the necessary component action boilerplate code.
+///
+/// The macro \a HPX_REGISTER_ACTION can be used to define all the
+/// boilerplate code which is required for proper functioning of component
+/// actions in the context of HPX.
+///
+/// The parameter \a action is the type of the action to define the
+/// boilerplate for.
+///
+/// \note This macro has to be used once for each of the component actions
+/// defined using one of the \a HPX_DEFINE_COMPONENT_ACTION macros. It has to
+/// occur exactly once for each of the actions, thus it is recommended to
+/// place it into the source file defining the component.
+#define HPX_REGISTER_ACTION(action)                                           \
+    HPX_REGISTER_ACTION_EX(action, action)                                    \
+/**/
+
 #endif
 

hpx/runtime/actions/component_action.hpp

@@ -4,6 +4,8 @@
 //  Distributed under the Boost Software License, Version 1.0. (See accompanying
 //  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+/// \file component_action.hpp
+
 #if !defined(HPX_RUNTIME_ACTIONS_COMPONENT_ACTION_MAR_26_2008_1054AM)
 #define HPX_RUNTIME_ACTIONS_COMPONENT_ACTION_MAR_26_2008_1054AM
 
@@ -32,6 +34,8 @@
 ///////////////////////////////////////////////////////////////////////////////
 namespace hpx { namespace actions
 {
+    /// \cond NOINTERNAL
+
     ///////////////////////////////////////////////////////////////////////////
 #define HPX_FUNCTION_ARG_ENUM(z, n, data)                                     \
         BOOST_PP_CAT(component_action_arg, BOOST_PP_INC(n)) =                 \
@@ -471,15 +475,92 @@ namespace hpx { namespace actions
     struct result_action0<Component, void, Action, F, Priority, Derived>
         : action0<Component, Action, F, Priority, Derived>
     {};
+
+    /// \endcond
 }}
 
-///////////////////////////////////////////////////////////////////////////////
-#define HPX_DEFINE_COMPONENT_ACTION(component, func, name)                    \
-    typedef HPX_MAKE_COMPONENT_ACTION(component, func) name                   \
+/// \def HPX_DEFINE_COMPONENT_ACTION(component, func, action_type)
+///
+/// \brief Registers a non-const member function of a component as an action type
+/// with HPX
+///
+/// The macro \a HPX_DEFINE_COMPONENT_CONST_ACTION can be used to register a
+/// non-const member function of a component as an action type named \a action_type.
+///
+/// The parameter \a component is the type of the component exposing the
+/// non-const member function \a func which should be associated with the newly
+/// defined action type. The parameter \p action_type is the name of the action
+/// type to register with HPX.
+///
+/// \par Example:
+///
+/// \code
+///       namespace app
+///       {
+///           // Define a simple component exposing one action 'print_greating'
+///           class HPX_COMPONENT_EXPORT server
+///             : public hpx::components::simple_component_base<server>
+///           {
+///               void print_greating ()
+///               {
+///                   hpx::cout << "Hey, how are you?\n" << hpx::flush;
+///               }
+///
+///               // Component actions need to be declared, this also defines the
+///               // type 'print_greating_action' representing the action.
+///               HPX_DEFINE_COMPONENT_ACTION(server, print_greating, print_greating_action);
+///           };
+///       }
+/// \endcode
+///
+/// \note This macro should be used for non-const member functions only. Use
+/// the macro \a HPX_DEFINE_COMPONENT_CONST_ACTION for const member functions.
+#define HPX_DEFINE_COMPONENT_ACTION(component, func, action_type)             \
+    typedef HPX_MAKE_COMPONENT_ACTION(component, func) action_type            \
     /**/
+
+/// \def HPX_DEFINE_COMPONENT_CONST_ACTION(component, func, action_type)
+///
+/// \brief Registers a const member function of a component as an action type
+/// with HPX
+///
+/// The macro \a HPX_DEFINE_COMPONENT_CONST_ACTION can be used to register a
+/// const member function of a component as an action type named \a action_type.
+///
+/// The parameter \a component is the type of the component exposing the const
+/// member function \a func which should be associated with the newly defined
+/// action type. The parameter \p action_type is the name of the action type to
+/// register with HPX.
+///
+/// \par Example:
+///
+/// \code
+///       namespace app
+///       {
+///           // Define a simple component exposing one action 'print_greating'
+///           class HPX_COMPONENT_EXPORT server
+///             : public hpx::components::simple_component_base<server>
+///           {
+///               void print_greating() const
+///               {
+///                   hpx::cout << "Hey, how are you?\n" << hpx::flush;
+///               }
+///
+///               // Component actions need to be declared, this also defines the
+///               // type 'print_greating_action' representing the action.
+///               HPX_DEFINE_COMPONENT_CONST_ACTION(server, print_greating, print_greating_action);
+///           };
+///       }
+/// \endcode
+///
+/// \note This macro should be used for const member functions only. Use
+/// the macro \a HPX_DEFINE_COMPONENT_ACTION for non-const member functions.
 #define HPX_DEFINE_COMPONENT_CONST_ACTION(component, func, name)              \
     typedef HPX_MAKE_CONST_COMPONENT_ACTION(component, func) name             \
     /**/
+
+/// \cond NOINTERNAL
+
 #define HPX_DEFINE_COMPONENT_DIRECT_ACTION(component, func, name)             \
     typedef HPX_MAKE_DIRECT_COMPONENT_ACTION(component, func) name            \
     /**/
@@ -510,6 +591,8 @@ HPX_SERIALIZATION_REGISTER_TEMPLATE(
     (template <typename Action>), (hpx::actions::transfer_action<Action>)
 )
 
+/// \endcond
+
 #include <hpx/config/warnings_suffix.hpp>
 
 #endif

hpx/runtime/actions/plain_action.hpp

@@ -30,11 +30,12 @@
 
 #include <hpx/config/warnings_prefix.hpp>
 
-/// \cond NOINTERNAL
 
 ///////////////////////////////////////////////////////////////////////////////
 namespace hpx { namespace actions
 {
+    /// \cond NOINTERNAL
+
     ///////////////////////////////////////////////////////////////////////////
 #define HPX_FUNCTION_ARG_ENUM(z, n, data)                                     \
         BOOST_PP_CAT(function_action_arg, BOOST_PP_INC(n)) =                  \
@@ -350,9 +351,10 @@ namespace hpx { namespace actions
     struct plain_result_action0<void, F, Priority, Derived>
         : plain_action0<F, Priority, Derived>
     {};
+
+    /// \endcond
 }}
 
-/// \endcond
 
 // Disabling the guid initialization stuff for plain actions
 namespace hpx { namespace traits
@@ -391,10 +393,10 @@ namespace hpx { namespace traits
 }}
 
 /// \def HPX_REGISTER_PLAIN_ACTION(action_type)
-/// \brief Registers an existing plain action type with HPX
+/// \brief Registers an existing free function as a plain action with HPX
 ///
 /// The macro \a HPX_REGISTER_PLAIN_ACTION can be used to register an existing
-/// plain action type (e.g. an action encapsulating a global or free function)
+/// free function as a plain action. It additionally defines an action type
 /// named \a action_type.
 ///
 /// The parameter \p action_type is the name of the action type to register