Changeset 59

Show
Ignore:
Timestamp:
12/16/06 01:54:02 (2 years ago)
Author:
KirkMcDonald
Message:

Docstring support

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/html_doc/basics.html

    r57 r59  
    4949<p>The <code>module_init</code> function has the following form:</p> 
    5050 
    51 <p><code>PyObject* module_init(char[] <span class="arg">name</span>);</code></p> 
     51<p><code>PyObject* module_init(char[] <span class="arg">name</span>, char[] <span class="arg">docstring</span>="");</code></p> 
    5252 
    5353<p>It does little more than call <a href="http://docs.python.org/api/allocating-objects.html">Py_InitModule</a> and return the new module object. This object is also available via the <code>Pyd_Module_p</code> property once you've called <code>module_init</code>.</p> 

  • trunk/html_doc/class_wrapping.html

    r58 r59  
    3939 
    4040<dl> 
    41 <dt><code>static void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn)) ();</code></dt> 
     41<dt><code>static void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn)) (char[] <span class="arg">docstring</span>="");</code></dt> 
    4242<dd>This wraps a method of the class. It functions exactly like the <code>def</code> function used to <a href="func_wrapping.html">wrap regular functions</a>, with one very important difference: There is no support for default arguments. (This is a side-effect of the fact that you cannot call an alias of a method in D, and delegates do not understand default arguments.)</dd> 
    4343 
    44 <dt><code>static void static_def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn), uint <span class="t_arg">MIN_ARGS</span> = minArgs!(fn)) ();</code></dt> 
     44<dt><code>static void static_def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn), uint <span class="t_arg">MIN_ARGS</span> = minArgs!(fn)) (char[] <span class="arg">docstring</span>="");</code></dt> 
    4545<dd>This wraps a static member function of the class. It also functions exactly like the <code>def</code> function used to wrap regular functions, and even includes support for default arguments.</dd> 
    4646 
    47 <dt><code>static void prop(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), bool <span class="t_arg">RO</span> = false) ();</code></dt> 
     47<dt><code>static void prop(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), bool <span class="t_arg">RO</span> = false) (char[] <span class="arg">docstring</span>="");</code></dt> 
    4848<dd>This wraps a property. See the examples below for more details. 
    4949    <ul> 
    …… 
    5151    <li><span class="t_arg">name</span> is the name of the property as it will appear in Python. As with <code>def</code>, <code>prop</code> will attempt to derive this automatically.</li> 
    5252    <li><span class="t_arg">RO</span> specifies whether this is a <i>read-only</i> property. If true, it will only wrap the "get" form of the property. If false, it will wrap both the "get" and "set" forms. <i>(This is a little hackish, and I will probably try to make this detection more automatic in the future. It also means it cannot support a property that only has a "set" form.)</i></li> 
     53    <li><span class="arg">docstring</span> is the property's docstring. As usual, note that this is a regular function argument, and not a template argument.</li> 
    5354    </ul> 
    5455</dd> 
    …… 
    6061<dd>This allows the user to specify a different overload of opApply than the default. (The default is always the one that is lexically first.) The <span class="t_arg">iter_t</span> argument should be the type of the delegate that forms the argument to opApply. This might be e.g. <code>int delegate(inout int)</code>. Don't forget the <code>inout</code> modifiers!</dd> 
    6162 
    62 <dt><code>static void alt_iter(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">iter_t</span> = <i>implementationDetail</i>) ();</code></dt> 
     63<dt><code>static void alt_iter(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">iter_t</span> = <i>implementationDetail</i>) (char[] <span class="arg">docstring</span>="");</code></dt> 
    6364<dd>This wraps alternate iterator methods as Python methods that return iterator objects. The wrapped methods should have a signature like that of opApply. (In other words, they should be methods intended to be used with D's ability to iterate over delgates.) The <span class="t_arg">iter_t</span> argument should be the type of the delegate argument to the method. This will usually be derived automatically. 
    6465</dd> 
    …… 
    6768<p>Once you have called all of the member functions of <code>wrapped_class</code> that you wish to, you must issue a call to <code>finalize_class</code>.</p> 
    6869 
    69 <p><code>void finalize_class(<span class="t_arg">CLS</span>) (<span class="t_arg">CLS</span> <span class="arg">cls</span>);</code></p> 
     70<p><code>void finalize_class(<span class="t_arg">CLS</span>) (<span class="t_arg">CLS</span> <span class="arg">cls</span>, char[] <span class="arg">docstring</span>="");</code></p> 
    7071 
    7172<p>This does some final initialization of the class and then registers it with Python. Unlike calls to <a href="func_wrapping.html"><code>def</code></a>, calls to <code>finalize_class</code> must occur <em>after</em> calling <code>module_init</code>. The <span class="arg">cls</span> function argument should be an instance of <code>wrapped_class</code>.</p> 

  • trunk/html_doc/func_wrapping.html

    r57 r59  
    3030<p>Exposing D functions to Python is easy! The heart of Pyd's function wrapping features is the <code>def</code> template function:</p> 
    3131 
    32 <p><code>void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn), uint <span class="t_arg">MIN_ARGS</span> = minArgs!(fn)) ();</code></p> 
     32<p><code>void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn), uint <span class="t_arg">MIN_ARGS</span> = minArgs!(fn)) (char[] <span class="arg">docstring</span>="");</code></p> 
    3333    <ul> 
    3434    <li><span class="t_arg">fn</span> is the function to wrap. Note that this is an alias parameter. <code>def</code> is only capable of wrapping full-fledged functions, not function pointers, function literals, or delegates.</li> 
    …… 
    3636    <li><span class="t_arg">fn_t</span> is the function type of the function. Typically, you won't have to specify this. It is used to wrap overloaded functions. (See below.)</li> 
    3737    <li><span class="t_arg">MIN_ARGS</span> is the minimum number of arguments this function can accept. It is used when a function has default arguments. The <code>minArgs</code> template can derive the correct number automatically, so you typically won't specify this manually.</li> 
     38    <li><span class="arg">docstring</span> is the function's docstring. Note that this is a regular function argument!</li> 
    3839    </ul> 
    3940 

  • trunk/html_doc/struct_wrapping.html

    r57 r59  
    3939 
    4040<dl> 
    41 <dt><code>static void member(<span class="t_arg">M</span>, size_t <span class="t_arg">offset</span>, char[] <span class="t_arg">name</span>) ();</code></dt> 
     41<dt><code>static void member(<span class="t_arg">M</span>, size_t <span class="t_arg">offset</span>, char[] <span class="t_arg">name</span>) (char[] <span class="arg">docstring</span>="");</code></dt> 
    4242<dd>This exposes a data member of the struct to Python. <span class="t_arg">M</span> is the type of the member, and must be a <a href="conversion.html">convertible type</a>. <span class="t_arg">offset</span> is the offset (in bytes) of the member in the struct. <span class="t_arg">name</span> is the name of the data member as it will be used in Python. <i>(Optimally, one would simply be able to pass an alias to the member, or at worst an alias and a name, but DMD currently has some issues with this.)</i></dd> 
    4343 
    44 <dt><code>static void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn)) ();</code></dt> 
     44<dt><code>static void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn)) (char[] <span class="arg">docstring</span>="");</code></dt> 
    4545<dd>This wraps a member function of the struct. It functions exactly like the <code>def</code> function used to <a href="class_wrapping.html">wrap class methods</a>, including the lack of support for default arguments.</dd> 
    4646 
    47 <dt><code>static void static_def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn), uint <span class="t_arg">MIN_ARGS</span> = minArgs!(fn)) ();</code></dt> 
     47<dt><code>static void static_def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">fn_t</span> = typeof(&amp;fn), uint <span class="t_arg">MIN_ARGS</span> = minArgs!(fn)) (char[] <span class="arg">docstring</span>="");</code></dt> 
    4848<dd>This wraps a static member function of the struct. It functions exactly like the <code>static_def</code> function used to wrap static class member functions, and also includes support for default arguments.</dd> 
    4949 
    50 <dt><code>static void prop(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), bool <span class="t_arg">RO</span> = false) ();</code></dt> 
     50<dt><code>static void prop(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), bool <span class="t_arg">RO</span> = false) (char[] <span class="arg">docstring</span>="");</code></dt> 
    5151<dd>This wraps a property. It is identical to the <code>prop</code> function used to <a href="class_wrapping.html">wrap class properties</a>.</dd> 
    5252 
    …… 
    5454<dd>This allows the user to specify a different overload of opApply than the default. (The default is always the one that is lexically first.) It is identical to the <code>iter</code> function used in <a href="class_wrapping.html">class wrapping</a>.</dd> 
    5555 
    56 <dt><code>static void alt_iter(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">iter_t</span> = <i>implementationDetail</i>) ();</code></dt> 
     56<dt><code>static void alt_iter(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span> = symbolnameof!(fn), <span class="t_arg">iter_t</span> = <i>implementationDetail</i>) (char[] <span class="arg">docstring</span>="");</code></dt> 
    5757<dd>This wraps alternate iterator methods as Python methods that return iterator objects. It is is identical to the <code>alt_iter</code> function used in <a href="class_wrapping.html">class wrapping</a>.</dd> 
    5858</dl> 
    …… 
    6262<p>Once you have called all of the member functions of <code>wrapped_struct</code> that you wish to, you must issue a call to <code>finalize_struct</code>.</p> 
    6363 
    64 <p><code>void finalize_struct(<span class="t_arg">S</span>) (<span class="t_arg">S</span> <span class="arg">s</span>);</code></p> 
     64<p><code>void finalize_struct(<span class="t_arg">S</span>) (<span class="t_arg">S</span> <span class="arg">s</span>, char[] <span class="arg">docstring</span>="");</code></p> 
    6565 
    6666<p>This does some final initialization of the type and then registers it with Python. As with calls to <a href="class_wrapping.html"><code>finalize_class</code></a>, calls to <code>finalize_struct</code> must occur <em>after</em> calling <code>module_init</code>. The <span class="arg">s</span> function argument should be an instance of <code>wrapped_struct</code>.</p> 

  • trunk/infrastructure/pyd/class_wrap.d

    r57 r59  
    251251     *        if more than one function has the same name as this one. 
    252252     */ 
    253     static void def(alias fn, char[] name = symbolnameof!(fn), fn_t=typeof(&fn)) () { 
     253    static void def(alias fn, char[] name = symbolnameof!(fn), fn_t=typeof(&fn)) (char[] docstring="") { 
    254254        pragma(msg, "class.def: " ~ name); 
    255255        static PyMethodDef empty = { null, null, 0, null }; 
    …… 
    258258        list[length-1].ml_meth = &method_wrap!(T, fn, fn_t).func; 
    259259        list[length-1].ml_flags = METH_VARARGS; 
    260         list[length-1].ml_doc = ""; 
     260        list[length-1].ml_doc = (docstring ~ \0).ptr; 
    261261        list ~= empty; 
    262262        // It's possible that appending the empty item invalidated the 
    …… 
    268268     * Wraps a static member function of the class. Identical to pyd.def.def 
    269269     */ 
    270     static void static_def(alias fn, char[] name = symbolnameof!(fn), fn_t=typeof(&fn), uint MIN_ARGS=minArgs!(fn)) () { 
     270    static void static_def(alias fn, char[] name = symbolnameof!(fn), fn_t=typeof(&fn), uint MIN_ARGS=minArgs!(fn)) (char[] docstring="") { 
    271271        pragma(msg, "class.static_def: " ~ name); 
    272272        static PyMethodDef empty = { null, null, 0, null }; 
    …… 
    275275        list[length-1].ml_meth = &function_wrap!(fn, MIN_ARGS, fn_t).func; 
    276276        list[length-1].ml_flags = METH_VARARGS | METH_STATIC; 
    277         list[length-1].ml_doc = ""; 
     277        list[length-1].ml_doc = (docstring ~ \0).ptr; 
    278278        list ~= empty; 
    279279        wrapped_class_type!(T).tp_methods = list; 
    …… 
    288288     * RO = Whether this is a read-only property. 
    289289     */ 
    290     static void prop(alias fn, char[] name = symbolnameof!(fn), bool RO=false) () { 
     290    static void prop(alias fn, char[] name = symbolnameof!(fn), bool RO=false) (char[] docstring="") { 
    291291        pragma(msg, "class.prop: " ~ name); 
    292292        static PyGetSetDef empty = { null, null, null, null, null }; 
    …… 
    298298                &wrapped_set!(T, fn).func; 
    299299        } 
    300         wrapped_prop_list!(T)[length-1].doc = ""; 
     300        wrapped_prop_list!(T)[length-1].doc = (docstring ~ \0).ptr; 
    301301        wrapped_prop_list!(T)[length-1].closure = null; 
    302302        wrapped_prop_list!(T) ~= empty; 
    …… 
    342342     * iterator. 
    343343     */ 
    344     static void alt_iter(alias fn, char[] name = symbolnameof!(fn), iter_t = funcDelegInfoT!(typeof(&fn)).Meta.ArgType!(0)) () { 
     344    static void alt_iter(alias fn, char[] name = symbolnameof!(fn), iter_t = funcDelegInfoT!(typeof(&fn)).Meta.ArgType!(0)) (char[] docstring="") { 
    345345        static PyMethodDef empty = { null, null, 0, null }; 
    346346        alias wrapped_method_list!(T) list; 
    …… 
    349349        list[length-1].ml_meth = cast(PyCFunction)&wrapped_iter!(T, fn, int function(iter_t)).iter; 
    350350        list[length-1].ml_flags = METH_VARARGS; 
    351         list[length-1].ml_doc = ""; 
     351        list[length-1].ml_doc = (docstring ~ \0).ptr; 
    352352        list ~= empty; 
    353353        // It's possible that appending the empty item invalidated the 
    …… 
    363363 * calls to the wrapped_class member functions. 
    364364 */ 
    365 void finalize_class(CLS) (CLS cls, char[] modulename="") { 
     365void finalize_class(CLS) (CLS cls, char[] docstring="", char[] modulename="") { 
    366366    alias CLS.wrapped_type T; 
    367367    alias wrapped_class_type!(T) type; 
    …… 
    379379    type.ob_type      = PyType_Type_p(); 
    380380    type.tp_basicsize = (wrapped_class_object!(T)).sizeof; 
    381     type.tp_doc       = (name ~ " objects" ~ \0).ptr; 
     381    type.tp_doc       = (docstring ~ \0).ptr; 
    382382    type.tp_flags     = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE; 
    383383    //type.tp_repr      = &wrapped_repr!(T).repr; 

  • trunk/infrastructure/pyd/def.d

    r55 r59  
    8282 *It's greater than 10!) 
    8383 */ 
    84 void def(alias fn, char[] name = symbolnameof!(fn), fn_t=typeof(&fn), uint MIN_ARGS = minArgs!(fn, fn_t)) () { 
    85     def!("", fn, name, fn_t, MIN_ARGS)(); 
     84void def(alias fn, char[] name = symbolnameof!(fn), fn_t=typeof(&fn), uint MIN_ARGS = minArgs!(fn, fn_t)) (char[] docstring="") { 
     85    def!("", fn, name, fn_t, MIN_ARGS)(docstring); 
    8686} 
    8787 
    88 void def(char[] modulename, alias fn, char[] name = symbolnameof!(fn), fn_t=typeof(&fn), uint MIN_ARGS = minArgs!(fn, fn_t)) () { 
     88void def(char[] modulename, alias fn, char[] name = symbolnameof!(fn), fn_t=typeof(&fn), uint MIN_ARGS = minArgs!(fn, fn_t)) (char[] docstring) { 
    8989    pragma(msg, "def: " ~ name); 
    9090    PyMethodDef empty; 
    …… 
    9595    (*list)[length-1].ml_meth = &function_wrap!(fn, MIN_ARGS, fn_t).func; 
    9696    (*list)[length-1].ml_flags = METH_VARARGS; 
    97     (*list)[length-1].ml_doc = ""; 
     97    (*list)[length-1].ml_doc = (docstring ~ \0).ptr; 
    9898    (*list) ~= empty; 
    9999} 
    …… 
    102102 * Module initialization function. Should be called after the last call to def. 
    103103 */ 
    104 PyObject* module_init(char[] name) { 
     104PyObject* module_init(char[] name, char[] docstring="") { 
    105105    //_loadPythonSupport(); 
    106106    ready_module_methods(""); 
    107     pyd_modules[""] = Py_InitModule((name ~ \0).ptr, module_methods[""].ptr); 
     107    pyd_modules[""] = Py_InitModule3((name ~ \0).ptr, module_methods[""].ptr, (docstring ~ \0).ptr); 
    108108    return pyd_modules[""]; 
    109109} 
    …… 
    112112 * Module initialization function. Should be called after the last call to def. 
    113113 */ 
    114 PyObject* add_module(char[] name) { 
     114PyObject* add_module(char[] name, char[] docstring="") { 
    115115    ready_module_methods(name); 
    116     pyd_modules[name] = Py_InitModule((name ~ \0).ptr, module_methods[name].ptr); 
     116    pyd_modules[name] = Py_InitModule3((name ~ \0).ptr, module_methods[name].ptr, (docstring ~ \0).ptr); 
    117117    return pyd_modules[name]; 
    118118} 

  • trunk/infrastructure/pyd/struct_wrap.d

    r54 r59  
    6767    alias T* wrapped_type; 
    6868 
    69     static void member(M, size_t offset, char[] name)() { 
     69    static void member(M, size_t offset, char[] name) (char[] docstring="") { 
    7070        pragma(msg, "struct.member: " ~ name); 
    7171        static PyGetSetDef empty = {null, null, null, null, null}; 
    …… 
    7474        list[length-1].get = &wrapped_member!(T*, M, offset).get; 
    7575        list[length-1].set = &wrapped_member!(T*, M, offset).set; 
    76         list[length-1].doc = ""; 
     76        list[length-1].doc = (docstring ~ \0).ptr; 
    7777        list[length-1].closure = null; 
    7878        list ~= empty;