Docs update

[SVN r13144]

include/boost/preprocessor/assert_msg.hpp

@@ -17,7 +17,10 @@
 #include <boost/preprocessor/logical/not.hpp>
 
 /** <p>Expands to nothing if <code>C != 0</code> and to <code>MSG</code> if
-<code>C == 0</code>.</p> */
+<code>C == 0</code>.</p>
+
+<p>For example, <code>BOOST_PP_ASSERT_MSG(1,A BUG!)</code> expands to <code>A BUG!</code>.</p>
+*/
 #define BOOST_PP_ASSERT_MSG(C,MSG) BOOST_PP_IF_THEN(BOOST_PP_NOT(C),MSG)
 
 /** <p>Obsolete. Use BOOST_PP_ASSERT_MSG().</p> */

include/boost/preprocessor/cat.hpp

@@ -16,6 +16,8 @@
 /** <p>Concatenates <code>X</code> and <code>Y</code> after they are macro
 expanded.</p>
 
+<p>For example, <code>BOOST_PP_CAT(A,BOOST_PP_CAT(_,B))</code> expands to <code>A_B</code>.</p>
+
 <h3>Example</h3>
 <ul>
   <li><a href="../../example/static_assert.c">static_assert.c</a></li>

include/boost/preprocessor/comma.hpp

@@ -13,7 +13,18 @@
  * See http://www.boost.org for most recent version.
  */
 
-/** <p>Expands to a comma. Can be used with BOOST_PP_IF().</p>
+/** <p>Expands to a comma.</p>
+
+<p>Commas need special handling in preprocessor code, because commas are used
+for separating macro parameters.</p>
+
+<p>For example,</p>
+
+<pre>
+  BOOST_PP_IF(1,BOOST_PP_COMMA,BOOST_PP_EMPTY)()
+</pre>
+
+<p>expands to a comma.</p>
 
 <h3>See</h3>
 <ul>

include/boost/preprocessor/comma_if.hpp

@@ -19,6 +19,8 @@
 
 /** <p>Expands to a comma if <code>C != 0</code> and nothing if
 <code>C == 0</code>.</p>
+
+<p>For example, <code>BOOST_PP_COMMA_IF(0)</code> expands to nothing.</p>
 */
 #define BOOST_PP_COMMA_IF(C) BOOST_PP_IF(C,BOOST_PP_COMMA,BOOST_PP_EMPTY)()
 

include/boost/preprocessor/comparison/equal.hpp

@@ -19,6 +19,8 @@
 /** <p>Expands to <code>1</code> if <code>X == Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code>BOOST_PP_EQUAL(4,4)</code> expands to <code>1</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_WHILE()</li>

include/boost/preprocessor/comparison/greater.hpp

@@ -18,6 +18,8 @@
 /** <p>Expands to <code>1</code> if <code>X &gt; Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code>BOOST_PP_GREATER(4,3)</code> expands to <code>1</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_WHILE()</li>

include/boost/preprocessor/comparison/greater_equal.hpp

@@ -18,6 +18,8 @@
 /** <p>Expands to <code>1</code> if <code>X &gt;= Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code>BOOST_PP_GREATER_EQUAL(1,3)</code> expands to <code>0</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_WHILE()</li>

include/boost/preprocessor/comparison/less.hpp

@@ -20,6 +20,8 @@
 /** <p>Expands to <code>1</code> if <code>X &lt; Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code>BOOST_PP_LESS(2,6)</code> expands to <code>1</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_WHILE()</li>

include/boost/preprocessor/comparison/less_equal.hpp

@@ -19,6 +19,8 @@
 /** <p>Expands to <code>1</code> if <code>X &lt;= Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code>BOOST_PP_LESS_EQUAL(7,5)</code> expands to <code>0</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_WHILE()</li>

include/boost/preprocessor/comparison/not_equal.hpp

@@ -20,6 +20,8 @@
 /** <p>Expands to <code>1</code> if <code>X != Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code>BOOST_PP_NOT_EQUAL(4,4)</code> expands to <code>0</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_WHILE()</li>

include/boost/preprocessor/empty.hpp

@@ -13,7 +13,15 @@
  * See http://www.boost.org for most recent version.
  */
 
-/** <p>Expands to nothing. Used with BOOST_PP_IF() and as an unused parameter.</p>
+/** <p>Expands to nothing.</p>
+
+<p>For example,</p>
+
+<pre>
+  BOOST_PP_IF(0,BOOST_PP_COMMA,BOOST_PP_EMPTY)()
+</pre>
+
+<p>expands to nothing.</p>
 
 <h3>Example</h3>
 <ul>

include/boost/preprocessor/enum.hpp

@@ -25,6 +25,20 @@
   F(0,P), F(1,P), ..., F(BOOST_PP_DEC(N),P)
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  #define TYPED_PARAM(I,P)\
+    BOOST_PP_CAT(BOOST_PP_TUPLE_ELEM(2,0,P),I) BOOST_PP_CAT(BOOST_PP_TUPLE_ELEM(2,1,P),I)
+  BOOST_PP_ENUM(3,TYPED_PARAM,(X,x))
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  X0 x0, X1 x1, X2 x2
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_REPEAT()</li>

include/boost/preprocessor/enum_params.hpp

@@ -24,6 +24,18 @@
   BOOST_PP_CAT(P,0), BOOST_PP_CAT(P,1), ..., BOOST_PP_CAT(P,BOOST_PP_DEC(N))
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  BOOST_PP_ENUM_PARAMS(3,x)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  x0, x1, x2
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_REPEAT()</li>

include/boost/preprocessor/enum_params_with_a_default.hpp

@@ -24,6 +24,18 @@
   BOOST_PP_CAT(P,0) = D, BOOST_PP_CAT(P,1) = D, ..., BOOST_PP_CAT(P,BOOST_PP_DEC(N)) = D
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  BOOST_PP_ENUM_PARAMS_WITH_A_DEFAULT(3,x,y)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  x0 = y, x1 = y, x2 = y
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_REPEAT()</li>

include/boost/preprocessor/enum_params_with_defaults.hpp

@@ -27,6 +27,18 @@
   BOOST_PP_CAT(P,BOOST_PP_DEC(N)) = BOOST_PP_CAT(D,BOOST_PP_DEC(N))
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  BOOST_PP_ENUM_PARAMS_WITH_DEFAULTS(3,x,y)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  x0 = y0, x1 = y1, x2 = y2
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_REPEAT()</li>

include/boost/preprocessor/enum_shifted.hpp

@@ -25,6 +25,20 @@
   F(1,P), F(2,P), ..., F(BOOST_PP_DEC(N),P)
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  #define TYPED_PARAM(I,P)\
+    BOOST_PP_CAT(BOOST_PP_TUPLE_ELEM(2,0,P),I) BOOST_PP_CAT(BOOST_PP_TUPLE_ELEM(2,1,P),I)
+  BOOST_PP_ENUM_SHIFTED(3,TYPED_PARAM,(X,x))
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  X1 x1, X2 x2
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li>BOOST_PP_REPEAT()</li>

include/boost/preprocessor/enum_shifted_params.hpp

@@ -23,6 +23,17 @@
 <pre>
   BOOST_PP_CAT(P,1), BOOST_PP_CAT(P,2), ..., BOOST_PP_CAT(P,BOOST_PP_DEC(N))
 </pre>
+<p>For example,</p>
+
+<pre>
+  BOOST_PP_ENUM_SHIFTED_PARAMS(3,x)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  x1, x2
+</pre>
 
 <h3>Uses</h3>
 <ul>

include/boost/preprocessor/for.hpp

@@ -44,6 +44,21 @@
       by the C++ preprocessor.</li>
 </ul>
 
+<p>For example,</p>
+
+<pre>
+  #define C(R,X) BOOST_PP_LESS(BOOST_PP_TUPLE_ELEM(2,0,X),BOOST_PP_TUPLE_ELEM(2,1,X))
+  #define F(R,X) (BOOST_PP_INC(BOOST_PP_TUPLE_ELEM(2,0,X)),BOOST_PP_TUPLE_ELEM(2,1,X))
+  #define I(R,X) BOOST_PP_TUPLE_ELEM(2,0,X)
+  BOOST_PP_FOR((0,3),C,F,I)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  0 1 2
+</pre>
+
 <h3>BOOST_PP_REPEAT() vs BOOST_PP_FOR()</h3>
 
 <p>BOOST_PP_FOR() is a generalization of BOOST_PP_REPEAT(). This means that

include/boost/preprocessor/if_then.hpp

@@ -13,10 +13,16 @@
  * See http://www.boost.org for most recent version.
  */
 
-#include <boost/preprocessor/empty.hpp>
-#include <boost/preprocessor/if.hpp>
+#include <boost/preprocessor/logical/bool.hpp>
 
 /** <p>Expands to <code>T</code> if <code>C != 0</code> and to nothing if <code>C == 0</code>.</p>
+
+<p>For example, <code>BOOST_PP_IF_THEN(1,^)</code> expands to <code>^</code>.</p>
 */
-#define BOOST_PP_IF_THEN(C,T) BOOST_PP_IF(C,T BOOST_PP_EMPTY,BOOST_PP_EMPTY)()
+#define BOOST_PP_IF_THEN(C,T) BOOST_PP_IF_THEN_BOOL(BOOST_PP_BOOL(C),T)
+
+#define BOOST_PP_IF_THEN_BOOL(C,T) BOOST_PP_IF_THEN_BOOL_DELAY(C,T)
+#define BOOST_PP_IF_THEN_BOOL_DELAY(C,T) BOOST_PP_IF_THEN_BOOL##C(T)
+#define BOOST_PP_IF_THEN_BOOL0(T)
+#define BOOST_PP_IF_THEN_BOOL1(T) T
 #endif