Menu
▾
▴
SF.net SVN: openvrml:[4168] trunk
|
From: <br...@us...> - 2010-08-07 20:57:52
|
Revision: 4168
http://openvrml.svn.sourceforge.net/openvrml/?rev=4168&view=rev
Author: braden
Date: 2010-08-07 20:57:46 +0000 (Sat, 07 Aug 2010)
Log Message:
-----------
Doc-comment improvements.
Modified Paths:
--------------
trunk/ChangeLog
trunk/src/libopenvrml/openvrml/node.cpp
trunk/src/libopenvrml/openvrml/node_impl_util.cpp
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2010-08-01 07:02:34 UTC (rev 4167)
+++ trunk/ChangeLog 2010-08-07 20:57:46 UTC (rev 4168)
@@ -1,3 +1,10 @@
+2010-08-07 Braden McDaniel <br...@en...>
+
+ Doc-comment improvements.
+
+ * src/libopenvrml/openvrml/node.cpp
+ * src/libopenvrml/openvrml/node_impl_util.cpp
+
2010-08-01 Braden McDaniel <br...@en...>
* README: Removed obsolete reference to OPENVRML_FT_CONST.
Modified: trunk/src/libopenvrml/openvrml/node.cpp
===================================================================
--- trunk/src/libopenvrml/openvrml/node.cpp 2010-08-01 07:02:34 UTC (rev 4167)
+++ trunk/src/libopenvrml/openvrml/node.cpp 2010-08-07 20:57:46 UTC (rev 4168)
@@ -725,8 +725,8 @@
* @c node_metatype can be thought of as a “supertype” of sorts.
* A given node implementation can support as many node types as there are
* unique combinations of the interfaces it supports. The most readily
- * apparent role of the @c node_metatype object for a node implementation is to
- * serve as a factory for these @c node_type%s.
+ * apparent role of the @c node_metatype object for a node implementation is
+ * to serve as a factory for these @c node_type%s.
*/
/**
@@ -887,6 +887,9 @@
*
* @brief Create a new @c node_type.
*
+ * Most %node implementations can use
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE to implement this function.
+ *
* @param[in] id the name for the new @c node_type.
* @param[in] interfaces a @c node_interface_set containing the
* interfaces for the new type.
@@ -899,6 +902,7 @@
* @exception std::bad_alloc if memory allocation fails.
*
* @sa #create_type
+ * @sa OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE
* @sa http://boost.org/libs/smart_ptr/shared_ptr.htm
*/
@@ -983,6 +987,18 @@
* @class openvrml::node_type openvrml/node.h
*
* @brief Type information object for @c node%s.
+ *
+ * Each implementation of a %node in %OpenVRML must have an associated
+ * concrete @c node_type that is capable of creating @c node%s with any subset
+ * of the implementation's supported %node interfaces. Because these can be
+ * somewhat tedious to create, %OpenVRML includes a good deal of machinery to
+ * facilitate the implementation of these classes. For most %node
+ * implementations, using @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE to
+ * implement @c node_metatype::do_create_type will generate an appropriate
+ * concrete @c node_type.
+ *
+ * @sa node_metatype::create_type
+ * @sa OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE
*/
/**
Modified: trunk/src/libopenvrml/openvrml/node_impl_util.cpp
===================================================================
--- trunk/src/libopenvrml/openvrml/node_impl_util.cpp 2010-08-01 07:02:34 UTC (rev 4167)
+++ trunk/src/libopenvrml/openvrml/node_impl_util.cpp 2010-08-07 20:57:46 UTC (rev 4168)
@@ -31,13 +31,15 @@
*
* @internal
*
+ * @hideinitializer
+ *
* @brief Get an element of a node interface tuple.
*
* @param index an index value from 0–3.
* @param tuple a node interface
* <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/data/tuples.html">tuple</a>
* as described for use with
- * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
*/
/**
@@ -45,12 +47,14 @@
*
* @internal
*
+ * @hideinitializer
+ *
* @brief Create an @c openvrml::node_interface from an interface tuple.
*
* @param interface_tuple a node interface
* <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/data/tuples.html">tuple</a>
* as described for use with
- * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
*/
/**
@@ -58,6 +62,8 @@
*
* @internal
*
+ * @hideinitializer
+ *
* @brief A helper macro used with
* @c <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/ref/seq_for_each_i.html">
* BOOST_PP_SEQ_FOR_EACH_I</a>.
@@ -68,7 +74,7 @@
* @param elem a node interface
* <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/data/tuples.html">tuple</a>
* as described for use with
- * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
*/
/**
@@ -76,17 +82,19 @@
*
* @internal
*
+ * @hideinitializer
+ *
* @brief The type of an array of supported @c openvrml::node_interface%s for
* a @c openvrml::node_metatype.
*
* This is a helper macro used in the implementation of
- * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
*
* @param interface_seq a <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/data/sequences.html">
* Boost.Preprocessor sequence</a> of
* <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/data/tuples.html">tuples</a>,
* as provided to
- * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
*/
/**
@@ -94,13 +102,15 @@
*
* @internal
*
- * @brief A helper macro used to implement @c OPENVRML_ADD_INTERFACE_TUPLE.
+ * @hideinitializer
*
+ * @brief A helper macro used to implement @c #OPENVRML_ADD_INTERFACE_TUPLE.
+ *
* @param node_type_obj a concrete @c openvrml::node_type instance.
* @param interface_type a node interface type name, in all lower-case, as
* described for use in the interface tuple
* provided to
- * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
* @param supported_interface a @c openvrml::node_interface.
* @param node a @c openvrml::node instance type.
* @param handler the name of a @p node member function that
@@ -112,8 +122,10 @@
*
* @internal
*
+ * @hideinitializer
+ *
* @brief A helper macro used to implement
- * @c OPENVRML_ADD_INTERFACE_ALTERNATIVE.
+ * @c #OPENVRML_ADD_INTERFACE_ALTERNATIVE.
*
* @param node_type_obj a concrete @c openvrml::node_type instance.
* @param node_instance_type a concrete @c openvrml::node instance type.
@@ -121,7 +133,7 @@
* @param interface_tuple a node interface
* <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/data/tuples.html">tuple</a>
* as described for use with
- * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
*/
/**
@@ -129,6 +141,8 @@
*
* @internal
*
+ * @hideinitializer
+ *
* @brief A helper macro used with
* @c <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/ref/seq_for_each.html">
* BOOST_PP_SEQ_FOR_EACH</a>.
@@ -144,15 +158,27 @@
* @param elem
*
* This macro is used in the implementation of
- * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE.
*/
/**
* @def OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE(namespace_scope, node_metatype_type, node_instance_type, interface_seq)
*
+ * @hideinitializer
+ *
* @brief Implement @c openvrml::node_metatype::do_create_type.
*
- * @p interface_seq consists of tuples of the following form:
+ * Most significantly, @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE
+ * generates a concrete @c openvrml::node_type implementation; by using this
+ * macro to implement @c openvrml::node_metatype::do_create_type, one can
+ * avoid manually creating a concrete @c openvrml::node_type.
+ *
+ * @c OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE is instantiated using a
+ * <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/index.html">
+ * Boost.Preprocessor</a> <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/data/sequences.html">sequence</a> of
+ * <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/data/tuples.html">
+ * tuples</a>. @p interface_seq consists of tuples of the following form:
+ *
* <pre>
* (@e interface-type, @e value-type, @e interface-id, @e handler)
* </pre>
@@ -195,6 +221,8 @@
* defining the supported interfaces for the node
* implementation and the @p node_instance_type
* member that implements them.
+ *
+ * @sa openvrml::node_metatype::do_create_type
*/
/**
@@ -406,9 +434,16 @@
/**
* @class openvrml::node_impl_util::node_type_impl openvrml/node_impl_util.h
*
- * @brief A template for concrete @c node_types.
+ * @brief A template for concrete @c node_type%s.
*
+ * @c node_type_impl is instantiated by
+ * @c #OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE to provide a concrete
+ * @c node_type implementation. Most node implementations can simply use that
+ * macro and consider this class template an implementation detail.
+ *
* @tparam Node a concrete node type.
+ *
+ * @sa OPENVRML_NODE_IMPL_UTIL_DEFINE_DO_CREATE_TYPE
*/
/**
@@ -1187,7 +1222,7 @@
* @brief Concrete pointer-to-member wrapper.
*
* @tparam EventEmitterMember the type of an @c openvrml::event_emitter
- * member of Node.
+ * member of @p Node.
*/
/**
@@ -1204,7 +1239,7 @@
*
* @brief Make an @c #event_emitter_ptr_ptr to a field member of a node.
*
- * @tparam EventEmitterMember an @c event_emitter member of Node.
+ * @tparam EventEmitterMember an @c event_emitter member of @p Node.
* @tparam DeducedNode the deduced type of the node may differ from
* its actual concrete type in the contexts in
* which this function is used. We @c static_cast
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
