From 1ad72e98a90a3427d2c2a7cff3d0ac2b7e355890 Mon Sep 17 00:00:00 2001
From: Vesa Karvonen <vesa.karvonen@housemarque.fi>
Date: Sat, 9 Mar 2002 13:55:00 +0000
Subject: [PATCH] Docs update

[SVN r13144]
---
 doc/reference/assert_msg.htm                      |  5 ++++-
 doc/reference/cat.htm                             |  2 ++
 doc/reference/comma.htm                           | 13 ++++++++++++-
 doc/reference/comma_if.htm                        |  2 ++
 doc/reference/comparison_equal.htm                |  2 ++
 doc/reference/comparison_greater.htm              |  2 ++
 doc/reference/comparison_greater_equal.htm        |  2 ++
 doc/reference/comparison_less.htm                 |  2 ++
 doc/reference/comparison_less_equal.htm           |  2 ++
 doc/reference/comparison_not_equal.htm            |  2 ++
 doc/reference/empty.htm                           | 10 +++++++++-
 doc/reference/enum.htm                            | 14 ++++++++++++++
 doc/reference/enum_params.htm                     | 12 ++++++++++++
 doc/reference/enum_params_with_a_default.htm      | 12 ++++++++++++
 doc/reference/enum_params_with_defaults.htm       | 12 ++++++++++++
 doc/reference/enum_shifted.htm                    | 14 ++++++++++++++
 doc/reference/enum_shifted_params.htm             | 11 +++++++++++
 doc/reference/for.htm                             | 15 +++++++++++++++
 doc/reference/if_then.htm                         |  2 ++
 include/boost/preprocessor/assert_msg.hpp         |  5 ++++-
 include/boost/preprocessor/cat.hpp                |  2 ++
 include/boost/preprocessor/comma.hpp              | 13 ++++++++++++-
 include/boost/preprocessor/comma_if.hpp           |  2 ++
 include/boost/preprocessor/comparison/equal.hpp   |  2 ++
 include/boost/preprocessor/comparison/greater.hpp |  2 ++
 .../preprocessor/comparison/greater_equal.hpp     |  2 ++
 include/boost/preprocessor/comparison/less.hpp    |  2 ++
 .../boost/preprocessor/comparison/less_equal.hpp  |  2 ++
 .../boost/preprocessor/comparison/not_equal.hpp   |  2 ++
 include/boost/preprocessor/empty.hpp              | 10 +++++++++-
 include/boost/preprocessor/enum.hpp               | 14 ++++++++++++++
 include/boost/preprocessor/enum_params.hpp        | 12 ++++++++++++
 .../preprocessor/enum_params_with_a_default.hpp   | 12 ++++++++++++
 .../preprocessor/enum_params_with_defaults.hpp    | 12 ++++++++++++
 include/boost/preprocessor/enum_shifted.hpp       | 14 ++++++++++++++
 .../boost/preprocessor/enum_shifted_params.hpp    | 11 +++++++++++
 include/boost/preprocessor/for.hpp                | 15 +++++++++++++++
 include/boost/preprocessor/if_then.hpp            | 12 +++++++++---
 38 files changed, 273 insertions(+), 9 deletions(-)

diff --git a/doc/reference/assert_msg.htm b/doc/reference/assert_msg.htm
index 9011897..d5d1734 100644
--- a/doc/reference/assert_msg.htm
+++ b/doc/reference/assert_msg.htm
@@ -28,7 +28,10 @@
 
 <h2><a name="BOOST_PP_ASSERT_MSG">#define BOOST_PP_ASSERT_MSG</a>(C,MSG)</h2>
  <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><a href="assert_msg.htm#BOOST_PP_ASSERT_MSG">BOOST_PP_ASSERT_MSG</a>(1,A BUG!)</code> expands to <code>A BUG!</code>.</p>
+
 <hr>
 
 <h2><a name="BOOST_PREPROCESSOR_ASSERT_MSG">#define BOOST_PREPROCESSOR_ASSERT_MSG</a>(C,MSG)</h2>
diff --git a/doc/reference/cat.htm b/doc/reference/cat.htm
index 974edfb..808f93a 100644
--- a/doc/reference/cat.htm
+++ b/doc/reference/cat.htm
@@ -30,6 +30,8 @@
  <p>Concatenates <code>X</code> and <code>Y</code> after they are macro
 expanded.</p>
 
+<p>For example, <code><a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(A,<a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(_,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>
diff --git a/doc/reference/comma.htm b/doc/reference/comma.htm
index 360fcdf..8c73d74 100644
--- a/doc/reference/comma.htm
+++ b/doc/reference/comma.htm
@@ -27,7 +27,18 @@
 <hr>
 
 <h2><a name="BOOST_PP_COMMA">#define BOOST_PP_COMMA</a>()</h2>
- <p>Expands to a comma. Can be used with <a href="if.htm#BOOST_PP_IF">BOOST_PP_IF</a>().</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>
+  <a href="if.htm#BOOST_PP_IF">BOOST_PP_IF</a>(1,<a href="comma.htm#BOOST_PP_COMMA">BOOST_PP_COMMA</a>,<a href="empty.htm#BOOST_PP_EMPTY">BOOST_PP_EMPTY</a>)()
+</pre>
+
+<p>expands to a comma.</p>
 
 <h3>See</h3>
 <ul>
diff --git a/doc/reference/comma_if.htm b/doc/reference/comma_if.htm
index fa7db35..06d37ad 100644
--- a/doc/reference/comma_if.htm
+++ b/doc/reference/comma_if.htm
@@ -30,6 +30,8 @@
  <p>Expands to a comma if <code>C != 0</code> and nothing if
 <code>C == 0</code>.</p>
 
+<p>For example, <code><a href="comma_if.htm#BOOST_PP_COMMA_IF">BOOST_PP_COMMA_IF</a>(0)</code> expands to nothing.</p>
+
 <hr>
 
 <h2><a name="BOOST_PREPROCESSOR_COMMA_IF">#define BOOST_PREPROCESSOR_COMMA_IF</a>(C)</h2>
diff --git a/doc/reference/comparison_equal.htm b/doc/reference/comparison_equal.htm
index 9b57669..6a9d8f3 100644
--- a/doc/reference/comparison_equal.htm
+++ b/doc/reference/comparison_equal.htm
@@ -30,6 +30,8 @@
  <p>Expands to <code>1</code> if <code>X == Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code><a href="comparison_equal.htm#BOOST_PP_EQUAL">BOOST_PP_EQUAL</a>(4,4)</code> expands to <code>1</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>()</li>
diff --git a/doc/reference/comparison_greater.htm b/doc/reference/comparison_greater.htm
index 22be6cc..1e7cd14 100644
--- a/doc/reference/comparison_greater.htm
+++ b/doc/reference/comparison_greater.htm
@@ -30,6 +30,8 @@
  <p>Expands to <code>1</code> if <code>X &gt; Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code><a href="comparison_greater.htm#BOOST_PP_GREATER">BOOST_PP_GREATER</a>(4,3)</code> expands to <code>1</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>()</li>
diff --git a/doc/reference/comparison_greater_equal.htm b/doc/reference/comparison_greater_equal.htm
index 4881b9e..476d771 100644
--- a/doc/reference/comparison_greater_equal.htm
+++ b/doc/reference/comparison_greater_equal.htm
@@ -30,6 +30,8 @@
  <p>Expands to <code>1</code> if <code>X &gt;= Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code><a href="comparison_greater_equal.htm#BOOST_PP_GREATER_EQUAL">BOOST_PP_GREATER_EQUAL</a>(1,3)</code> expands to <code>0</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>()</li>
diff --git a/doc/reference/comparison_less.htm b/doc/reference/comparison_less.htm
index 453552e..62bef5c 100644
--- a/doc/reference/comparison_less.htm
+++ b/doc/reference/comparison_less.htm
@@ -30,6 +30,8 @@
  <p>Expands to <code>1</code> if <code>X &lt; Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code><a href="comparison_less.htm#BOOST_PP_LESS">BOOST_PP_LESS</a>(2,6)</code> expands to <code>1</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>()</li>
diff --git a/doc/reference/comparison_less_equal.htm b/doc/reference/comparison_less_equal.htm
index 4aa1341..f4ad193 100644
--- a/doc/reference/comparison_less_equal.htm
+++ b/doc/reference/comparison_less_equal.htm
@@ -30,6 +30,8 @@
  <p>Expands to <code>1</code> if <code>X &lt;= Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code><a href="comparison_less_equal.htm#BOOST_PP_LESS_EQUAL">BOOST_PP_LESS_EQUAL</a>(7,5)</code> expands to <code>0</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>()</li>
diff --git a/doc/reference/comparison_not_equal.htm b/doc/reference/comparison_not_equal.htm
index cfef7a4..edfe7dd 100644
--- a/doc/reference/comparison_not_equal.htm
+++ b/doc/reference/comparison_not_equal.htm
@@ -30,6 +30,8 @@
  <p>Expands to <code>1</code> if <code>X != Y</code> and <code>0</code>
 otherwise.</p>
 
+<p>For example, <code><a href="comparison_not_equal.htm#BOOST_PP_NOT_EQUAL">BOOST_PP_NOT_EQUAL</a>(4,4)</code> expands to <code>0</code>.</p>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>()</li>
diff --git a/doc/reference/empty.htm b/doc/reference/empty.htm
index 428d0d0..84f78b2 100644
--- a/doc/reference/empty.htm
+++ b/doc/reference/empty.htm
@@ -27,7 +27,15 @@
 <hr>
 
 <h2><a name="BOOST_PP_EMPTY">#define BOOST_PP_EMPTY</a>()</h2>
- <p>Expands to nothing. Used with <a href="if.htm#BOOST_PP_IF">BOOST_PP_IF</a>() and as an unused parameter.</p>
+ <p>Expands to nothing.</p>
+
+<p>For example,</p>
+
+<pre>
+  <a href="if.htm#BOOST_PP_IF">BOOST_PP_IF</a>(0,<a href="comma.htm#BOOST_PP_COMMA">BOOST_PP_COMMA</a>,<a href="empty.htm#BOOST_PP_EMPTY">BOOST_PP_EMPTY</a>)()
+</pre>
+
+<p>expands to nothing.</p>
 
 <h3>Example</h3>
 <ul>
diff --git a/doc/reference/enum.htm b/doc/reference/enum.htm
index 5f75465..f037990 100644
--- a/doc/reference/enum.htm
+++ b/doc/reference/enum.htm
@@ -35,6 +35,20 @@
   F(0,P), F(1,P), ..., F(<a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(N),P)
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  #define TYPED_PARAM(I,P)\
+    <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,0,P),I) <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,1,P),I)
+  <a href="enum.htm#BOOST_PP_ENUM">BOOST_PP_ENUM</a>(3,TYPED_PARAM,(X,x))
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  X0 x0, X1 x1, X2 x2
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>()</li>
diff --git a/doc/reference/enum_params.htm b/doc/reference/enum_params.htm
index 6892d04..9f4b9a6 100644
--- a/doc/reference/enum_params.htm
+++ b/doc/reference/enum_params.htm
@@ -35,6 +35,18 @@
   <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,0), <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,1), ..., <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,<a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(N))
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  <a href="enum_params.htm#BOOST_PP_ENUM_PARAMS">BOOST_PP_ENUM_PARAMS</a>(3,x)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  x0, x1, x2
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>()</li>
diff --git a/doc/reference/enum_params_with_a_default.htm b/doc/reference/enum_params_with_a_default.htm
index f433f81..bd7732e 100644
--- a/doc/reference/enum_params_with_a_default.htm
+++ b/doc/reference/enum_params_with_a_default.htm
@@ -35,6 +35,18 @@
   <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,0) = D, <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,1) = D, ..., <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,<a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(N)) = D
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  <a href="enum_params_with_a_default.htm#BOOST_PP_ENUM_PARAMS_WITH_A_DEFAULT">BOOST_PP_ENUM_PARAMS_WITH_A_DEFAULT</a>(3,x,y)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  x0 = y, x1 = y, x2 = y
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>()</li>
diff --git a/doc/reference/enum_params_with_defaults.htm b/doc/reference/enum_params_with_defaults.htm
index 3153c55..2e4443a 100644
--- a/doc/reference/enum_params_with_defaults.htm
+++ b/doc/reference/enum_params_with_defaults.htm
@@ -38,6 +38,18 @@
   <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,<a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(N)) = <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(D,<a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(N))
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  <a href="enum_params_with_defaults.htm#BOOST_PP_ENUM_PARAMS_WITH_DEFAULTS">BOOST_PP_ENUM_PARAMS_WITH_DEFAULTS</a>(3,x,y)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  x0 = y0, x1 = y1, x2 = y2
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>()</li>
diff --git a/doc/reference/enum_shifted.htm b/doc/reference/enum_shifted.htm
index 22a477c..5a7901a 100644
--- a/doc/reference/enum_shifted.htm
+++ b/doc/reference/enum_shifted.htm
@@ -35,6 +35,20 @@
   F(1,P), F(2,P), ..., F(<a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(N),P)
 </pre>
 
+<p>For example,</p>
+
+<pre>
+  #define TYPED_PARAM(I,P)\
+    <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,0,P),I) <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,1,P),I)
+  <a href="enum_shifted.htm#BOOST_PP_ENUM_SHIFTED">BOOST_PP_ENUM_SHIFTED</a>(3,TYPED_PARAM,(X,x))
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  X1 x1, X2 x2
+</pre>
+
 <h3>Uses</h3>
 <ul>
   <li><a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>()</li>
diff --git a/doc/reference/enum_shifted_params.htm b/doc/reference/enum_shifted_params.htm
index 2b69905..d1c53df 100644
--- a/doc/reference/enum_shifted_params.htm
+++ b/doc/reference/enum_shifted_params.htm
@@ -34,6 +34,17 @@
 <pre>
   <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,1), <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,2), ..., <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(P,<a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(N))
 </pre>
+<p>For example,</p>
+
+<pre>
+  <a href="enum_shifted_params.htm#BOOST_PP_ENUM_SHIFTED_PARAMS">BOOST_PP_ENUM_SHIFTED_PARAMS</a>(3,x)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  x1, x2
+</pre>
 
 <h3>Uses</h3>
 <ul>
diff --git a/doc/reference/for.htm b/doc/reference/for.htm
index c530ffb..037a3fa 100644
--- a/doc/reference/for.htm
+++ b/doc/reference/for.htm
@@ -55,6 +55,21 @@
       by the C++ preprocessor.</li>
 </ul>
 
+<p>For example,</p>
+
+<pre>
+  #define C(R,X) <a href="comparison_less.htm#BOOST_PP_LESS">BOOST_PP_LESS</a>(<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,0,X),<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,1,X))
+  #define F(R,X) (<a href="inc.htm#BOOST_PP_INC">BOOST_PP_INC</a>(<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,0,X)),<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,1,X))
+  #define I(R,X) <a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(2,0,X)
+  <a href="for.htm#BOOST_PP_FOR">BOOST_PP_FOR</a>((0,3),C,F,I)
+</pre>
+
+<p>expands to:</p>
+
+<pre>
+  0 1 2
+</pre>
+
 <h3><a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>() vs <a href="for.htm#BOOST_PP_FOR">BOOST_PP_FOR</a>()</h3>
 
 <p><a href="for.htm#BOOST_PP_FOR">BOOST_PP_FOR</a>() is a generalization of <a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>(). This means that
diff --git a/doc/reference/if_then.htm b/doc/reference/if_then.htm
index 50251d0..7b1d6f7 100644
--- a/doc/reference/if_then.htm
+++ b/doc/reference/if_then.htm
@@ -29,6 +29,8 @@
 <h2><a name="BOOST_PP_IF_THEN">#define BOOST_PP_IF_THEN</a>(C,T)</h2>
  <p>Expands to <code>T</code> if <code>C != 0</code> and to nothing if <code>C == 0</code>.</p>
 
+<p>For example, <code><a href="if_then.htm#BOOST_PP_IF_THEN">BOOST_PP_IF_THEN</a>(1,^)</code> expands to <code>^</code>.</p>
+
 <hr>
 
 <a href="if.htm">Prev</a> <a href="inc.htm">Next</a> <a href="index.htm#Macros">Macros</a> <a href="index.htm#Headers">Headers</a>
diff --git a/include/boost/preprocessor/assert_msg.hpp b/include/boost/preprocessor/assert_msg.hpp
index ff384d0..37ecff7 100644
--- a/include/boost/preprocessor/assert_msg.hpp
+++ b/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> */
diff --git a/include/boost/preprocessor/cat.hpp b/include/boost/preprocessor/cat.hpp
index b778f9f..f2445a9 100644
--- a/include/boost/preprocessor/cat.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/comma.hpp b/include/boost/preprocessor/comma.hpp
index c12ddb2..51ae2ad 100644
--- a/include/boost/preprocessor/comma.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/comma_if.hpp b/include/boost/preprocessor/comma_if.hpp
index 3c34a11..89bfb77 100644
--- a/include/boost/preprocessor/comma_if.hpp
+++ b/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)()
 
diff --git a/include/boost/preprocessor/comparison/equal.hpp b/include/boost/preprocessor/comparison/equal.hpp
index 9ac98e3..b9452b2 100644
--- a/include/boost/preprocessor/comparison/equal.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/comparison/greater.hpp b/include/boost/preprocessor/comparison/greater.hpp
index 25d2f1f..38c5fb3 100644
--- a/include/boost/preprocessor/comparison/greater.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/comparison/greater_equal.hpp b/include/boost/preprocessor/comparison/greater_equal.hpp
index 69a2668..233dbb3 100644
--- a/include/boost/preprocessor/comparison/greater_equal.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/comparison/less.hpp b/include/boost/preprocessor/comparison/less.hpp
index d516d3c..129f2bb 100644
--- a/include/boost/preprocessor/comparison/less.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/comparison/less_equal.hpp b/include/boost/preprocessor/comparison/less_equal.hpp
index ead56bb..0d849e3 100644
--- a/include/boost/preprocessor/comparison/less_equal.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/comparison/not_equal.hpp b/include/boost/preprocessor/comparison/not_equal.hpp
index 8ef2ad4..c89e1b3 100644
--- a/include/boost/preprocessor/comparison/not_equal.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/empty.hpp b/include/boost/preprocessor/empty.hpp
index 7073850..7de23ae 100644
--- a/include/boost/preprocessor/empty.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/enum.hpp b/include/boost/preprocessor/enum.hpp
index 3e4b238..d5e3daa 100644
--- a/include/boost/preprocessor/enum.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/enum_params.hpp b/include/boost/preprocessor/enum_params.hpp
index 2ea06be..4805752 100644
--- a/include/boost/preprocessor/enum_params.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/enum_params_with_a_default.hpp b/include/boost/preprocessor/enum_params_with_a_default.hpp
index 4d99a41..018fdc6 100644
--- a/include/boost/preprocessor/enum_params_with_a_default.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/enum_params_with_defaults.hpp b/include/boost/preprocessor/enum_params_with_defaults.hpp
index bfd5c8c..806f48f 100644
--- a/include/boost/preprocessor/enum_params_with_defaults.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/enum_shifted.hpp b/include/boost/preprocessor/enum_shifted.hpp
index 43b95de..2a2f990 100644
--- a/include/boost/preprocessor/enum_shifted.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/enum_shifted_params.hpp b/include/boost/preprocessor/enum_shifted_params.hpp
index 40792b8..fed6396 100644
--- a/include/boost/preprocessor/enum_shifted_params.hpp
+++ b/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>
diff --git a/include/boost/preprocessor/for.hpp b/include/boost/preprocessor/for.hpp
index a03748f..4a91e76 100644
--- a/include/boost/preprocessor/for.hpp
+++ b/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
diff --git a/include/boost/preprocessor/if_then.hpp b/include/boost/preprocessor/if_then.hpp
index 725f242..a850d81 100644
--- a/include/boost/preprocessor/if_then.hpp
+++ b/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