Subject: [Boost-commit] svn:boost r65829 - sandbox/variadic_macro_data/libs/variadic_macro_data/doc
From: eldiener_at_[hidden]
Date: 2010-10-08 11:39:11
Author: eldiener
Date: 2010-10-08 11:39:06 EDT (Fri, 08 Oct 2010)
New Revision: 65829
URL: http://svn.boost.org/trac/boost/changeset/65829
Log:
Changes and additions
Added:
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDComparison.qbk (contents, props changed)
Text files modified:
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDFunctionality.qbk | 27 ++++++++++++++++-----------
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk | 4 ++--
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDVariadicMacros.qbk | 12 ++++++++----
sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VariadicMacroData.qbk | 1 +
4 files changed, 27 insertions(+), 17 deletions(-)
Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDComparison.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDComparison.qbk 2010-10-08 11:39:06 EDT (Fri, 08 Oct 2010)
@@ -0,0 +1,28 @@
+[section:vmd_comparison Variadic Macro Data Library and Boost PP]
+
+Boost PP already has the ability to pass variadic data
+as a single macro argument through any of its data types.
+It may then be reasonably asked why there is any need to
+use variadic macros instead.
+
+There are two major considerations for using variadic macros:
+
+# The syntax for using variadic macros is the more natural
+ syntax for passing macro arguments. Providing a comma-separated
+ list of data mimics the way macro arguments are usually passed.
+# The length of the variadic data does not have to be passed.
+ In Boost PP the length does not have to be passed for the
+ sequences and lists, but it is passed as part of an arrays, and
+ must be separately passed for tuples. Functionality in this library,
+ however, alleviates this last requirement for tuples.
+
+On the other hand there is one major consideration for using
+Boost PP data types for passing variadic data to macros. This
+is the fact that Boost PP data types can be passed multiple
+times in any macro whereas variadic macros can only pass its
+variadic macro data a single time as the final set of arguments
+to a macro. Nonetheless I feel that the more natural syntax of
+variadic macro data still provides enough importance for using
+this library's facilities for variadic macros.
+
+[endsect]
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDFunctionality.qbk
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDFunctionality.qbk (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDFunctionality.qbk 2010-10-08 11:39:06 EDT (Fri, 08 Oct 2010)
@@ -5,9 +5,9 @@
which can be treated as a single preprocessor argument to a macro.
A number of Boost PP macros accept data as a single argument. Each
of these data types also has its own rich set of macros to manipulate
-the data. It is imperative that when interoperating with Boost PP
-data be passed as a single argument, even though the data itself
-may consist of a number of preprocessing tokens.
+the data. It is imperative when interoperating with Boost PP that
+data is able to be passed as a single argument, even though the data
+itself may consist of a number of preprocessing tokens.
In variadic macros the data to be passed as variadic macro data is
a comma-separated list of arguments, each of which can be any
@@ -15,18 +15,23 @@
Because the variadic macro data is more than a single token, in
order to use variadic macro data with Boost PP, it is
-necessary to be able to convert the variadic macro data as a whole
-to a single argument Boost PP data type. Alternatively one can extract
-from the variadic macro data any given token and use that as a single
-argument, or possibly combine individual tokens from the variadic
-macro data into Boost PP data types using the functionality of any
-given Boost PP data type to do so.
+necessary to be able to convert the variadic macro data
+to a single argument Boost PP data type. One can do this either by
+converting the variadic macro data as a whole, by extracting any given
+token from the variadic macro data and use that as a single argument,
+or by combining individual tokens from the variadic
+macro data into Boost PP data types using the functionality of the
+Boost PP data type to do so.
The variadic macro data library provides means to interoperate
-variadic macro data with Boost PP in either general case.
+variadic macro data with Boost PP in these ways.
Outside of Boost PP interoperability, the variadic macro data library
allows individual tokens to be extracted from the variadic macro data
-and used in macro expansion in all the normal ways one may write macros.
+and used in macro expansion or passed to other macross.
+
+Finally through the functionality of variadic macros, the variadic macro
+data library provides parallel functionality to the Boost PP tuple
+interface macros which does not need the size of a tuple to be specified.
[endsect]
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk 2010-10-08 11:39:06 EDT (Fri, 08 Oct 2010)
@@ -3,8 +3,8 @@
The variadic macro data library is a library of macros which
provide important functionality for variadic macros as well as
integrating variadic macros with the Boost preprocessor library,
-which will afterwards be referred to as just 'Boost PP' in this
-documentation. It integrates with Boost PP without changing the
+to be referred to as just 'Boost PP' in this documentation.
+It integrates with Boost PP without changing the
latter library in any way.
The functionality of the library may be summed up as:
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDVariadicMacros.qbk
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDVariadicMacros.qbk (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDVariadicMacros.qbk 2010-10-08 11:39:06 EDT (Fri, 08 Oct 2010)
@@ -6,10 +6,14 @@
series of comma-separated tokens. In the macro expansion a special
keyword of '\_\_VA\_ARGS\_\_' represents the comma-separated tokens. This
information when passed to a variadic macro I call 'variadic macro data',
-which gives its name to this library. C99, and by implication C++0x,
-provides no built-in way of accessing a single token from the
-comma-separated list of variadic macro data. But this library does
-provide a means to do that among its other functionality.
+which gives its name to this library. The more general term 'variadic data'
+is used in this documentation to specify data passed to a macro which can
+contain any number of macro tokens as a single macro parameter, such as is
+found in Boost PP.
+
+C99, and by implication C++0x, provides no built-in way of accessing a
+single token from the comma-separated list of variadic macro data. But this
+library does provide a means to do that among its other functionality.
[section:vmd_vmacros_Boost Boost support]
Modified: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VariadicMacroData.qbk
==============================================================================
--- sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VariadicMacroData.qbk (original)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VariadicMacroData.qbk 2010-10-08 11:39:06 EDT (Fri, 08 Oct 2010)
@@ -17,4 +17,5 @@
[include VMDDetail.qbk]
[include VMDReference.qbk]
[include VMDDesign.qbk]
+[include VMDComparison.qbk]
[include VMDAcknowledgements.qbk]