From e13d09242cb0cd8806c0f3f60d75923b2a0119e8 Mon Sep 17 00:00:00 2001
From: Dave Abrahams <dave@boostpro.com>
Date: Tue, 1 Oct 2002 17:22:26 +0000
Subject: [PATCH] doc update

[SVN r15621]
---
 doc/v2/class.html     |  24 ++--
 doc/v2/init.html      | 250 ++++++++++++++++++++++++++++++++++++++++++
 doc/v2/overloads.html | 225 +++++++++++++++++++++++++++++++++++++
 3 files changed, 489 insertions(+), 10 deletions(-)
 create mode 100644 doc/v2/init.html
 create mode 100644 doc/v2/overloads.html
diff --git a/doc/v2/class.html b/doc/v2/class.html
index 768a1444..c3e95f74 100644
--- a/doc/v2/class.html
+++ b/doc/v2/class.html
@@ -345,7 +345,7 @@ class_&amp; def(Init init_expr);
       generated constructs an object of <code>HeldType</code> according to
       the semantics described <a href="#HeldType">above</a>, using a copy of
       <code>init_expr</code>'s <a href="CallPolicies.html">call policies</a>.
-      If the longest valid prefix of <code>Init</code> contains <em>N</em>
+      If the longest <a href="init.html#init-expressions">valid prefix</a> of <code>Init</code> contains <em>N</em>
       types and <code>init_expr</code> holds <em>M</em> keywords, an initial
       sequence of the keywords are used for all but the first
       <em>N</em>&nbsp;-&nbsp;<em>M</em> arguments of each overload.</dt>
@@ -378,17 +378,21 @@ class_&amp; def(char const* name, Fn fn, A1 const&amp; a1, A2 const&amp; a2, A3
         <ul>
           <li>
             If <code>a1</code> is the result of an <a href=
-            "OverloadDispatch.html"><em>overload-dispatch-expression</em></a>,
-            only the second is allowed and fn must be a pointer to function
-            or pointer to member function whose signature is compatible with
-            A1. 
+            "overloads.html#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>,
+            only the second form is allowed and fn must be a pointer
+            to function or pointer to member function whose <a
+            href="definitions.html#arity">arity</a> is the same as A1's <a href=
+            "overloads.html#overload-dispatch-expression"><em>maximum arity</em></a>.
 
             <dl>
-              <dt><b>Effects:</b> For each <a href=
-              "OverloadDispatch.html#valid-prefix">valid prefix</a>
-              <em>P</em> of <code>A1</code>, adds a
-              <code><em>name</em>(</code>...<code>)</code> function overload
-              to the extension class. Each overload generated invokes
+              <dt><b>Effects:</b> For each prefix <em>P</em> of
+              <code>Fn</code>'s sequence of argument types, beginning
+            with the one whose length is <code>A1</code>'s <a href=
+            "overloads.html#overload-dispatch-expression"><em>minimum
+            arity</em></a>, adds a
+              <code><em>name</em>(</code>...<code>)</code> method
+              overload to the extension class. Each overload generated
+              invokes
               <code>a1</code>'s call-expression with <em>P</em>, using a copy
               of <code>a1</code>'s <a href="CallPolicies.html">call
               policies</a>. If the longest valid prefix of <code>A1</code>
diff --git a/doc/v2/init.html b/doc/v2/init.html
new file mode 100644
index 00000000..710287ef
--- /dev/null
+++ b/doc/v2/init.html
@@ -0,0 +1,250 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+  <head>
+    <meta name="generator" content=
+    "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/init.hpp&gt;</title>
+  </head>
+
+  <body link="#0000ff" vlink="#800080">
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277"
+          alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+        </td>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Headers &lt;boost/python/init.hpp&gt;,
+          &lt;boost/python/class_fwd.hpp&gt;</h2>
+        </td>
+      </tr>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a></dt>
+
+              <dt><a href=
+              "#init-expressions"><em>init-expressions</em></a></dt>
+
+      <dt><a href="#classes">Classes</a></dt>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href="#init-spec">Class template <code>init</code></a></dt>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#init-spec-synopsis">Class template
+              <code>init</code> synopsis</a></dt>
+
+              <dt><a href="#init-spec-ctors">Class <code>init</code>
+              constructors</a></dt>
+
+            </dl>
+          </dd>
+
+          <dt><a href="#optional-spec">Class template
+          <code>optional</code></a></dt>
+
+          <dd>
+            <dl class="page-index">
+              <dt><a href="#optional-spec-synopsis">Class template
+              <code>optional</code> synopsis</a></dt>
+            </dl>
+          </dd>
+        </dl>
+      </dd>
+
+      <dt><a href="#examples">Example(s)</a></dt>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p><code>&lt;boost/python/init.hpp&gt;</code> defines the interface for
+    exposing C++ constructors to Python as extension class
+    <code>__init__</code> functions.</p>
+
+    <h2><a name="init-expressions"><em>init-expressions</em></a></h2>
+    An <em>init-expression</em> is used to describe a family of
+    <code>__init__</code> methods to be generated for an extension class, and
+    the result has the following properties: 
+
+    <blockquote>
+      <dl class="properties">
+        <dt><b>docstring:</b> An <a href="definitions.html#ntbs">ntbs</a>
+        whose value will bound to the method's <code>__doc__</code>
+        attribute</dt>
+
+        <dt><b>keywords:</b> A <a href=
+        "args.html#keyword-expression">keyword-expression</a> which will be
+        used to name (a trailing subsequence of) the arguments to the
+        generated <code>__init__</code> function(s).</dt>
+
+        <dt><b>call policies:</b> An instance of a model of <a href=
+        "CallPolicies.html">CallPolicies</a>.</dt>
+
+        <dt><b>argument types:</b> An MPL sequence of C++ argument types
+        which will be used to construct the wrapped C++ object. An init
+        expression has one or more 
+        <b>valid prefixes</b> which are given by a sequence of
+        prefixes of its argument types.</dt>
+      </dl>
+    </blockquote>
+
+    <h2><a name="classes"></a>Classes</h2>
+
+    <h3><a name="init-spec"></a>Class template <code>init&lt;T1 =</code>
+    <i>unspecified</i><code>,&nbsp;T2 =</code>
+    <i>unspecified</i><code>,</code>...<code>Tn</code> =
+    <i>unspecified</i><code>&gt;</code></h3>
+
+    <p>A <a href="../../../mpl/doc/ref/Sequences.html">MPL sequence</a> which
+    can be used to specify a family of one or more <code>__init__</code>
+    functions. Only the last <code>T</code><i><small>i</small></i> supplied
+    may be an instantiation of <a href=
+    "#optional-spec"><code>optional</code></a><code>&lt;</code>...<code>&gt;</code>.</p>
+
+    <h4><a name="init-spec-synopsis"></a>Class template <code>init</code>
+    synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>&gt;
+  struct init
+  {
+      init(char const* doc = 0);
+      template &lt;class Keywords&gt; init(Keywords const&amp; kw, char const* doc = 0);
+      template &lt;class Keywords&gt; init(char const* doc, Keywords const&amp; kw);
+
+      template &lt;class CallPolicies&gt;
+      <em>unspecified</em> operator[](CallPolicies const&amp; policies) const
+  };
+}}
+</pre>
+
+    <h4><a name="init-spec-ctors"></a>Class template <code>init</code>
+    constructors</h4>
+<pre>
+init(char const* doc = 0);
+template &lt;class Keywords&gt; init(Keywords const&amp; kw, char const* doc = 0);
+template &lt;class Keywords&gt; init(char const* doc, Keywords const&amp; kw);
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> If supplied, <code>doc</code> is an <a href=
+      "definitions.html#ntbs">ntbs</a>. If supplied, <code>kw</code> is the
+      result of a <a href="args.html#keyword-expression"></a></dt>
+
+      <dt><b>Effects:</b> The result is an <em>init-expression</em> whose
+      <em>docstring</em> is <code>doc</code> and whose <em>keywords</em> are
+      a reference to <code>kw</code>. If the first form is used, the
+      resulting expression's <em>keywords</em> are empty. The expression's
+      <em>call policies</em> are an instance of <a href=
+      "default_call_policies.html#default_call_policies-spec">default_call_policies</a>.
+      If <code>T</code><i><small>n</small></i> is <a href=
+      "#optional-spec"><code>optional</code></a><code>&lt;U1,&nbsp;U2,</code>...
+      <code>U</code><small><i>m</i></small><code>&gt;</code>, the
+      expression's <em>valid prefixes</em> are given by:</dt>
+
+      <dd>
+        <blockquote>
+          (<code>T1,&nbsp;T2,</code>...<code>T</code><i><small>n-1</small></i>),
+          (<code>T1,&nbsp;T2,</code>...<code>T</code><i><small>n-1</small></i>
+          <code>,&nbsp;U1</code>),
+          (<code>T1,&nbsp;T2,</code>...<code>T</code><i><small>n-1</small></i>
+          <code>,&nbsp;U1,&nbsp;U2</code>),
+          ...(<code>T1,&nbsp;T2,</code>...<code>T</code><i><small>n-1</small></i>
+          <code>,&nbsp;U1,&nbsp;U2,</code>...<code>U</code><i><small>m</small></i>).
+        </blockquote>
+        Otherwise, the expression has one <em>valid prefix</em> given by the
+        the template arguments the user specified.
+      </dd>
+    </dl>
+
+    <h4><a name="init-spec-observers"></a>Class template <code>init</code>
+    observer functions</h4>
+<pre>
+template &lt;class Policies&gt;
+<em>unspecified</em> operator[](Policies const&amp; policies) const
+</pre>
+
+    <dl class="function-semantics">
+      <dt><b>Requires:</b> Policies is a model of <a href=
+      "CallPolicies.html">CallPolicies</a>.</dt>
+
+      <dt><b>Effects:</b> Returns a new <a href=
+      "#init-expressions"><em>init-expression</em></a> with all the same
+      properties as the <code>init</code> object except that its <em>call
+      policies</em> are replaced by a reference to
+      <code>policies</code>.</dt>
+    </dl>
+
+    <h3><a name="optional-spec"></a>Class template <code>optional&lt;T1
+    =</code> <i>unspecified</i><code>,&nbsp;T2 =</code>
+    <i>unspecified</i><code>,</code>...<code>Tn</code> =
+    <i>unspecified</i><code>&gt;</code></h3>
+
+    <p>A <a href="../../../mpl/doc/ref/Sequences.html">MPL sequence</a> which
+    can be used to specify the optional arguments to an <code>__init__</code>
+    function.</p>
+
+    <h4><a name="optional-spec-synopsis"></a>Class template
+    <code>optional</code> synopsis</h4>
+<pre>
+namespace boost { namespace python
+{
+  template &lt;T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>&gt;
+  struct optional {};
+}}
+</pre>
+
+    <h2><a name="examples"></a>Example(s)</h2>
+
+    <p>Given the C++ declarations:</p>
+<pre>
+class Y;
+class X
+{
+ public:
+   X(int x, Y* y) : m_y(y) {}
+   X(double);
+ private:
+   Y* m_y;
+};
+</pre>
+    A corresponding Boost.Python extension class can be created with: 
+<pre>
+using namespace boost::python;
+
+class_&lt;X&gt;("X", "This is X's docstring.",
+          init&lt;int,char const*&gt;(args("x","y"), "X.__init__'s docstring")[
+                with_custodian_and_ward&lt;1,3&gt;()]
+          )
+   .def(init&lt;double&gt;())
+   ;
+</pre>
+    <hr>
+    Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     1 October, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+     
+
+    <p><i>&copy; Copyright <a href=
+    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
+    Reserved.</i></p>
+  </body>
+</html>
+
diff --git a/doc/v2/overloads.html b/doc/v2/overloads.html
new file mode 100644
index 00000000..3e931980
--- /dev/null
+++ b/doc/v2/overloads.html
@@ -0,0 +1,225 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+  <head>
+    <meta name="generator" content=
+    "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+    <link rel="stylesheet" type="text/css" href="../boost.css">
+
+    <title>Boost.Python - &lt;boost/python/overloads.hpp&gt;</title>
+  </head>
+
+  <body>
+    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
+    "header">
+      <tr>
+        <td valign="top" width="300">
+          <h3><a href="../../../../index.htm"><img height="86" width="277"
+          alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
+        </td>
+
+        <td valign="top">
+          <h1 align="center">Boost.Python</h1>
+
+          <h2 align="center">Header &lt;boost/python/overloads.hpp&gt;</h2>
+        </td>
+      </tr>
+    </table>
+    <hr>
+
+    <h2>Contents</h2>
+
+    <dl class="page-index">
+      <dt><a href="#introduction">Introduction</a></dt>
+
+      <dt><a href=
+      "#overload-dispatch-expression"><i>overload-dispatch-expressions</i></a></dt>
+
+      <dt><a href= "#OverloadDispatcher-concept">OverloadDispatcher</a> concept</dt>
+
+      <dt><a href="#macros">Macros</a></dt>
+
+      <dd>
+        <dl class="page-index">
+          <dt><a href=
+          "#BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS</a></dt>
+
+          <dt><a href=
+          "#BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</a></dt>
+        </dl>
+      </dd>
+
+      <dt><a href="#examples">Example(s)</a></dt>
+    </dl>
+    <hr>
+
+    <h2><a name="introduction"></a>Introduction</h2>
+
+    <p>Defines facilities for generating families of overloaded Python
+    functions and extension class methods from C++ functions and
+    member functions with default arguments, or from similar families
+    of C++ overloads</p>
+
+    <h2><a name=
+    "overload-dispatch-expression"></a><i>overload-dispatch-expressions</i></h2>
+
+    <p>
+    An <em>overload-dispatch-expression</em> is used to describe a
+    family of overloaded methods to be generated for an extension
+    class. It has the following properties:
+
+    <blockquote>
+      <dl class="properties">
+        <dt><b>docstring:</b> An <a href="definitions.html#ntbs">ntbs</a>
+        whose value will bound to the methods' <code>__doc__</code>
+        attribute</dt>
+
+        <dt><b>keywords:</b> A <a href=
+        "args.html#keyword-expression">keyword-expression</a> which
+        will be used to name (a trailing subsequence of) the arguments
+        to the generated methods.</dt>
+
+        <dt><b>call policies:</b> An instance of some type which models <a href=
+        "CallPolicies.html">CallPolicies</a>.</dt>
+
+        <dt><b>minimum <a href="definitions.html#arity">arity</a></b>
+        The minimum number of arguments to be accepted by a generated
+        method overload.</dt>
+
+        <dt><b>maximum <a href="definitions.html#arity">arity</a></b>
+        The maximum number of arguments to be accepted by a generated
+        method overload.</dt>
+      </dl>
+    </blockquote>
+
+    <h2><a name="OverloadDispatcher-concept"></a>OverloadDispatcher Concept</h2>
+
+    An OverloadDispatcher <code>X</code> is a class which has a
+    <em>minimum arity</em> and a <em>maximum arity</em>, and for which
+    the following following are valid <a
+    href="#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>s,
+    with the same minimum and maximum arity as the OverloadDispatcher.
+
+<pre>
+X()
+X(docstring)
+X(docstring, keywords)
+X(keywords, docstring)
+X()[policies]
+X(docstring)[policies]
+X(docstring, keywords)[policies]
+X(keywords, docstring)[policies]
+</pre>
+
+<ul>
+<li>If <code>policies</code> are supplied, it must be an instance of a
+type which models <a
+href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>, and
+will be used as the result's call policies. Otherwise the result's
+call policies will be an instance of <a
+href="default_call_policies.html#default_call_policies-spec">default_call_policies</a>.
+
+<li>If <code>docstring</code> is supplied it must be an <a
+href="definitions.html#ntbs">ntbs</a>, and will be used as the result's docstring. Otherwise the result has an empty docstring.
+
+<li>If <code>keywords</code> is supplied it must be the result of a <a
+        href= "args.html#keyword-expression">keyword-expression</a>
+        whose length is no greater than <code>X</code>'s maximum
+        arity, and will be used as the result's keywords. Otherwise
+        the result's keywords will be empty.
+</ul>
+
+
+
+
+    <h2><a name="macros"></a>Macros</h2>
+
+    <h3><a name=
+    "BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS(name,&nbsp;func_id,&nbsp;min_args,&nbsp;max_args)</a></h3>
+    Expands to the definition of an OverloadDispatcher called
+    <code>name</code> in the current scope which can be used to
+    generate the following function invocation:
+<pre>
+func_id(a<small><i>1</i></small>, a<small><i>2</i></small>,...a<small><i>i</i></small>);
+</pre>
+
+   for all <code>min_args</code> &lt;= <i>i</i> &lt;= <code>max_args</code>.
+
+    <h3><a name=
+    "BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(name,&nbsp;member_name,&nbsp;min_args,&nbsp;max_args)</a></h3>
+
+    Expands to the definition of an OverloadDispatcher called
+    <code>name</code> in the current scope which can be used to
+    generate the following function invocation:
+<pre>
+x.member_name(a<small><i>1</i></small>, a<small><i>2</i></small>,...a<small><i>i</i></small>);
+</pre>
+
+   for all <code>min_args</code> &lt;= <i>i</i> &lt;=
+   <code>max_args</code>, where <code>x</code> is a reference to an
+   object of class type.
+
+    <h2><a name="examples"></a>Example(s)</h2>
+
+<pre>
+#include &lt;boost/python/module.hpp&gt;
+#include &lt;boost/python/def.hpp&gt;
+#include &lt;boost/python/args.hpp&gt;
+#include &lt;boost/python/tuple.hpp&gt;
+#include &lt;boost/python/class.hpp&gt;
+#include &lt;boost/python/overloads.hpp&gt;
+#include &lt;boost/python/return_internal_reference.hpp&gt;
+
+using namespace boost::python;
+
+tuple f(int x = 1, double y = 4.25, char const* z = &quot;wow&quot;)
+{
+    return make_tuple(x, y, z);
+}
+
+BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3)
+
+stryct Y {};
+struct X
+{
+    Y&amp; f(int x, double y = 4.25, char const* z = &quot;wow&quot;)
+    {
+        return inner;
+    }
+    Y inner;
+};
+
+BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_f_overloads, X::f, 1, 3)
+
+BOOST_PYTHON_MODULE(args_ext)
+{
+    def(&quot;f&quot;, f, args(&quot;x&quot;, &quot;y&quot;, &quot;z&quot;)
+        , &quot;This is f's docstring&quot;
+        );
+
+    
+    class_&lt;Y&gt;(&quot;Y&quot;)
+        ;
+            
+    class_&lt;X&gt;(&quot;X&quot;, &quot;This is X's docstring&quot;)
+        .def(&quot;f1&quot;, &amp;X::f, 
+                X_f_overloads(args(&quot;x&quot;, &quot;y&quot;, &quot;z&quot;),
+                              &quot;f's docstring&quot;
+                                  )[return_internal_reference&lt;&gt;()])
+        ;
+}
+</pre>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
+     01 October, 2002 
+    <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
+    </p>
+
+    <p><i>&copy; Copyright <a href=
+    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
+    Reserved.</i></p>
+  </body>
+</html>
+
