jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

pep257 & numpydoc conforming docstrings

Browse source
This commit is contained in:
xantares 2015-04-13 11:15:18 +02:00 • committed by William S Fulton
commit 92328a2016
4 changed files with 156 additions and 124 deletions
Download patch file Download diff file Expand all files Collapse all files

37
Doc/Manual/Python.html
View file

@ -5273,8 +5273,8 @@ def function_name(*args, **kwargs):
<p> <p>
Level "2" results in the function prototype as per level "0". In addition, a line of Level "2" results in the function prototype as per level "0". In addition, a line of
documentation is generated for each parameter. Using the previous example, the generated documentation is generated for each parameter using <a href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpydoc</a> style.
code will be: Using the previous example, the generated code will be:
</p> </p>
<div class="targetlang"> <div class="targetlang">
@ -5283,11 +5283,12 @@ def function_name(*args, **kwargs):
""" """
function_name(x, y, foo=None, bar=None) -&gt; bool function_name(x, y, foo=None, bar=None) -&gt; bool
Parameters: Parameters
x: int ----------
y: int x: int
foo: Foo * y: int
bar: Bar * foo: Foo *
bar: Bar *
""" """
... ...
@ -5318,11 +5319,12 @@ def function_name(*args, **kwargs):
""" """
function_name(x, y, foo=None, bar=None) -&gt; bool function_name(x, y, foo=None, bar=None) -&gt; bool
Parameters: Parameters
x (C++ type: int) -- Input x dimension ----------
y: int x (C++ type: int) -- Input x dimension
foo: Foo * y: int
bar: Bar * foo: Foo *
bar: Bar *
""" """
</pre> </pre>
@ -5341,11 +5343,12 @@ def function_name(*args, **kwargs):
""" """
function_name(int x, int y, Foo foo=None, Bar bar=None) -&gt; bool function_name(int x, int y, Foo foo=None, Bar bar=None) -&gt; bool
Parameters: Parameters
x: int ----------
y: int x: int
foo: Foo * y: int
bar: Bar * foo: Foo *
bar: Bar *
""" """
... ...

4
Examples/test-suite/autodoc.i
View file

@ -1,4 +1,4 @@
%module(docstring="hello") autodoc %module(docstring="hello.") autodoc
%feature("autodoc"); %feature("autodoc");
@ -27,7 +27,7 @@
%feature("autodoc","2") A::variable_c; // extended %feature("autodoc","2") A::variable_c; // extended
%feature("autodoc","3") A::variable_d; // extended + types %feature("autodoc","3") A::variable_d; // extended + types
%feature("autodoc","just a string") A::funk; // names %feature("autodoc","just a string.") A::funk; // names
%inline { %inline {

222
Examples/test-suite/python/autodoc_runme.py
View file

@ -23,8 +23,8 @@ if not is_new_style_class(A):
# skip builtin check - the autodoc is missing, but it probably should not be # skip builtin check - the autodoc is missing, but it probably should not be
skip = True skip = True
check(A.__doc__, "Proxy of C++ A class", "::A") check(A.__doc__, "Proxy of C++ A class.", "::A")
check(A.funk.__doc__, "just a string") check(A.funk.__doc__, "just a string.")
check(A.func0.__doc__, check(A.func0.__doc__,
"func0(self, arg2, hello) -> int", "func0(self, arg2, hello) -> int",
"func0(arg2, hello) -> int") "func0(arg2, hello) -> int")
@ -35,17 +35,19 @@ check(A.func2.__doc__,
"\n" "\n"
" func2(self, arg2, hello) -> int\n" " func2(self, arg2, hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" arg2: short\n" " ----------\n"
" hello: int tuple[2]\n" " arg2: short\n"
" hello: int tuple[2]\n"
"\n" "\n"
" ", " ",
"\n" "\n"
"func2(arg2, hello) -> int\n" "func2(arg2, hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" arg2: short\n" "----------\n"
" hello: int tuple[2]\n" "arg2: short\n"
"hello: int tuple[2]\n"
"\n" "\n"
"" ""
) )
@ -53,17 +55,19 @@ check(A.func3.__doc__,
"\n" "\n"
" func3(A self, short arg2, Tuple hello) -> int\n" " func3(A self, short arg2, Tuple hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" arg2: short\n" " ----------\n"
" hello: int tuple[2]\n" " arg2: short\n"
" hello: int tuple[2]\n"
"\n" "\n"
" ", " ",
"\n" "\n"
"func3(short arg2, Tuple hello) -> int\n" "func3(short arg2, Tuple hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" arg2: short\n" "----------\n"
" hello: int tuple[2]\n" "arg2: short\n"
"hello: int tuple[2]\n"
"\n" "\n"
"" ""
) )
@ -92,35 +96,39 @@ check(A.func2default.__doc__,
"\n" "\n"
" func2default(self, e, arg3, hello, f=2) -> int\n" " func2default(self, e, arg3, hello, f=2) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" e: A *\n" " ----------\n"
" arg3: short\n" " e: A *\n"
" hello: int tuple[2]\n" " arg3: short\n"
" f: double\n" " hello: int tuple[2]\n"
" f: double\n"
"\n" "\n"
" func2default(self, e, arg3, hello) -> int\n" " func2default(self, e, arg3, hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" e: A *\n" " ----------\n"
" arg3: short\n" " e: A *\n"
" hello: int tuple[2]\n" " arg3: short\n"
" hello: int tuple[2]\n"
"\n" "\n"
" ", " ",
"\n" "\n"
"func2default(e, arg3, hello, f=2) -> int\n" "func2default(e, arg3, hello, f=2) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" e: A *\n" "----------\n"
" arg3: short\n" "e: A *\n"
" hello: int tuple[2]\n" "arg3: short\n"
" f: double\n" "hello: int tuple[2]\n"
"f: double\n"
"\n" "\n"
"func2default(e, arg3, hello) -> int\n" "func2default(e, arg3, hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" e: A *\n" "----------\n"
" arg3: short\n" "e: A *\n"
" hello: int tuple[2]\n" "arg3: short\n"
"hello: int tuple[2]\n"
"\n" "\n"
"" ""
) )
@ -128,35 +136,39 @@ check(A.func3default.__doc__,
"\n" "\n"
" func3default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n" " func3default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" e: A *\n" " ----------\n"
" arg3: short\n" " e: A *\n"
" hello: int tuple[2]\n" " arg3: short\n"
" f: double\n" " hello: int tuple[2]\n"
" f: double\n"
"\n" "\n"
" func3default(A self, A e, short arg3, Tuple hello) -> int\n" " func3default(A self, A e, short arg3, Tuple hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" e: A *\n" " ----------\n"
" arg3: short\n" " e: A *\n"
" hello: int tuple[2]\n" " arg3: short\n"
" hello: int tuple[2]\n"
"\n" "\n"
" ", " ",
"\n" "\n"
"func3default(A e, short arg3, Tuple hello, double f=2) -> int\n" "func3default(A e, short arg3, Tuple hello, double f=2) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" e: A *\n" "----------\n"
" arg3: short\n" "e: A *\n"
" hello: int tuple[2]\n" "arg3: short\n"
" f: double\n" "hello: int tuple[2]\n"
"f: double\n"
"\n" "\n"
"func3default(A e, short arg3, Tuple hello) -> int\n" "func3default(A e, short arg3, Tuple hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" e: A *\n" "----------\n"
" arg3: short\n" "e: A *\n"
" hello: int tuple[2]\n" "arg3: short\n"
"hello: int tuple[2]\n"
"\n" "\n"
"" ""
) )
@ -185,35 +197,39 @@ check(A.func2static.__doc__,
"\n" "\n"
" func2static(e, arg2, hello, f=2) -> int\n" " func2static(e, arg2, hello, f=2) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" e: A *\n" " ----------\n"
" arg2: short\n" " e: A *\n"
" hello: int tuple[2]\n" " arg2: short\n"
" f: double\n" " hello: int tuple[2]\n"
" f: double\n"
"\n" "\n"
" func2static(e, arg2, hello) -> int\n" " func2static(e, arg2, hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" e: A *\n" " ----------\n"
" arg2: short\n" " e: A *\n"
" hello: int tuple[2]\n" " arg2: short\n"
" hello: int tuple[2]\n"
"\n" "\n"
" ", " ",
"\n" "\n"
"func2static(e, arg2, hello, f=2) -> int\n" "func2static(e, arg2, hello, f=2) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" e: A *\n" "----------\n"
" arg2: short\n" "e: A *\n"
" hello: int tuple[2]\n" "arg2: short\n"
" f: double\n" "hello: int tuple[2]\n"
"f: double\n"
"\n" "\n"
"func2static(e, arg2, hello) -> int\n" "func2static(e, arg2, hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" e: A *\n" "----------\n"
" arg2: short\n" "e: A *\n"
" hello: int tuple[2]\n" "arg2: short\n"
"hello: int tuple[2]\n"
"\n" "\n"
"" ""
) )
@ -221,35 +237,39 @@ check(A.func3static.__doc__,
"\n" "\n"
" func3static(A e, short arg2, Tuple hello, double f=2) -> int\n" " func3static(A e, short arg2, Tuple hello, double f=2) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" e: A *\n" " ----------\n"
" arg2: short\n" " e: A *\n"
" hello: int tuple[2]\n" " arg2: short\n"
" f: double\n" " hello: int tuple[2]\n"
" f: double\n"
"\n" "\n"
" func3static(A e, short arg2, Tuple hello) -> int\n" " func3static(A e, short arg2, Tuple hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" e: A *\n" " ----------\n"
" arg2: short\n" " e: A *\n"
" hello: int tuple[2]\n" " arg2: short\n"
" hello: int tuple[2]\n"
"\n" "\n"
" ", " ",
"\n" "\n"
"func3static(A e, short arg2, Tuple hello, double f=2) -> int\n" "func3static(A e, short arg2, Tuple hello, double f=2) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" e: A *\n" "----------\n"
" arg2: short\n" "e: A *\n"
" hello: int tuple[2]\n" "arg2: short\n"
" f: double\n" "hello: int tuple[2]\n"
"f: double\n"
"\n" "\n"
"func3static(A e, short arg2, Tuple hello) -> int\n" "func3static(A e, short arg2, Tuple hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" e: A *\n" "----------\n"
" arg2: short\n" "e: A *\n"
" hello: int tuple[2]\n" "arg2: short\n"
"hello: int tuple[2]\n"
"\n" "\n"
"" ""
) )
@ -268,8 +288,9 @@ if sys.version_info[0:2] > (2, 4):
"\n" "\n"
"A_variable_c_get(self) -> int\n" "A_variable_c_get(self) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" self: A *\n" "----------\n"
"self: A *\n"
"\n", "\n",
"A.variable_c" "A.variable_c"
) )
@ -277,14 +298,15 @@ if sys.version_info[0:2] > (2, 4):
"\n" "\n"
"A_variable_d_get(A self) -> int\n" "A_variable_d_get(A self) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
" self: A *\n" "----------\n"
"self: A *\n"
"\n", "\n",
"A.variable_d" "A.variable_d"
) )
check(B.__doc__, check(B.__doc__,
"Proxy of C++ B class", "Proxy of C++ B class.",
"::B" "::B"
) )
check(C.__init__.__doc__, "__init__(self, a, b, h) -> C", None, skip) check(C.__init__.__doc__, "__init__(self, a, b, h) -> C", None, skip)
@ -294,10 +316,11 @@ check(E.__init__.__doc__,
"\n" "\n"
" __init__(self, a, b, h) -> E\n" " __init__(self, a, b, h) -> E\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" a: special comment for parameter a\n" " ----------\n"
" b: another special comment for parameter b\n" " a: special comment for parameter a\n"
" h: enum Hola\n" " b: another special comment for parameter b\n"
" h: enum Hola\n"
"\n" "\n"
" ", None, skip " ", None, skip
) )
@ -305,10 +328,11 @@ check(F.__init__.__doc__,
"\n" "\n"
" __init__(F self, int a, int b, Hola h) -> F\n" " __init__(F self, int a, int b, Hola h) -> F\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" a: special comment for parameter a\n" " ----------\n"
" b: another special comment for parameter b\n" " a: special comment for parameter a\n"
" h: enum Hola\n" " b: another special comment for parameter b\n"
" h: enum Hola\n"
"\n" "\n"
" ", None, skip " ", None, skip
) )

17
Source/Modules/python.cxx
View file

@ -799,7 +799,11 @@ public:
Swig_register_filebyname("python", f_shadow); Swig_register_filebyname("python", f_shadow);
if (mod_docstring && Len(mod_docstring)) { if (mod_docstring && Len(mod_docstring)) {
Printv(f_shadow, "\"\"\"\n", mod_docstring, "\n\"\"\"\n\n", NIL); const char *triple_double = "\"\"\"";
// follow PEP257 rules: https://www.python.org/dev/peps/pep-0257/
// reported by pep257: https://github.com/GreenSteam/pep257
const bool multi_line_ds = Strchr(mod_docstring, '\n');
Printv(f_shadow, triple_double, multi_line_ds?"\n":"", mod_docstring, multi_line_ds?"\n":"", triple_double, "\n\n", NIL);
Delete(mod_docstring); Delete(mod_docstring);
mod_docstring = NULL; mod_docstring = NULL;
} }
@ -1795,8 +1799,9 @@ public:
Append(doc, name); Append(doc, name);
if (pdoc) { if (pdoc) {
if (!pdocs) if (!pdocs)
pdocs = NewString("\nParameters:\n"); // numpydoc style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Printf(pdocs, " %s\n", pdoc); pdocs = NewString("\nParameters\n----------\n");
Printf(pdocs, "%s\n", pdoc);
} }
// Write the function annotation // Write the function annotation
if (func_annotation) if (func_annotation)
@ -1892,9 +1897,9 @@ public:
Delete(rname); Delete(rname);
} else { } else {
if (CPlusPlus) { if (CPlusPlus) {
Printf(doc, "Proxy of C++ %s class", real_classname); Printf(doc, "Proxy of C++ %s class.", real_classname);
} else { } else {
Printf(doc, "Proxy of C %s struct", real_classname); Printf(doc, "Proxy of C %s struct.", real_classname);
} }
} }
} }
@ -4329,7 +4334,7 @@ public:
if (have_docstring(n)) { if (have_docstring(n)) {
String *str = docstring(n, AUTODOC_CLASS, tab4); String *str = docstring(n, AUTODOC_CLASS, tab4);
if (str && Len(str)) if (str && Len(str))
Printv(f_shadow, tab4, str, "\n", NIL); Printv(f_shadow, tab4, str, "\n\n", NIL);
} }
if (!modern) { if (!modern) {