[Boost-commit] svn:boost r65829 - sandbox/variadic_macro_data/libs/variadic_macro_data/doc

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]