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

13
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,7 +5283,8 @@ 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 x: int
y: int y: int
foo: Foo * foo: Foo *
@ -5318,7 +5319,8 @@ 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 x (C++ type: int) -- Input x dimension
y: int y: int
foo: Foo * foo: Foo *
@ -5341,7 +5343,8 @@ 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 x: int
y: int y: int
foo: Foo * foo: Foo *

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 {

78
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,7 +35,8 @@ check(A.func2.__doc__,
"\n" "\n"
" func2(self, arg2, hello) -> int\n" " func2(self, arg2, hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" ----------\n"
" arg2: short\n" " arg2: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
"\n" "\n"
@ -43,7 +44,8 @@ check(A.func2.__doc__,
"\n" "\n"
"func2(arg2, hello) -> int\n" "func2(arg2, hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
"----------\n"
"arg2: short\n" "arg2: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
"\n" "\n"
@ -53,7 +55,8 @@ 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"
" ----------\n"
" arg2: short\n" " arg2: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
"\n" "\n"
@ -61,7 +64,8 @@ check(A.func3.__doc__,
"\n" "\n"
"func3(short arg2, Tuple hello) -> int\n" "func3(short arg2, Tuple hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
"----------\n"
"arg2: short\n" "arg2: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
"\n" "\n"
@ -92,7 +96,8 @@ 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"
" ----------\n"
" e: A *\n" " e: A *\n"
" arg3: short\n" " arg3: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
@ -100,7 +105,8 @@ check(A.func2default.__doc__,
"\n" "\n"
" func2default(self, e, arg3, hello) -> int\n" " func2default(self, e, arg3, hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" ----------\n"
" e: A *\n" " e: A *\n"
" arg3: short\n" " arg3: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
@ -109,7 +115,8 @@ check(A.func2default.__doc__,
"\n" "\n"
"func2default(e, arg3, hello, f=2) -> int\n" "func2default(e, arg3, hello, f=2) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
"----------\n"
"e: A *\n" "e: A *\n"
"arg3: short\n" "arg3: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
@ -117,7 +124,8 @@ check(A.func2default.__doc__,
"\n" "\n"
"func2default(e, arg3, hello) -> int\n" "func2default(e, arg3, hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
"----------\n"
"e: A *\n" "e: A *\n"
"arg3: short\n" "arg3: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
@ -128,7 +136,8 @@ 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"
" ----------\n"
" e: A *\n" " e: A *\n"
" arg3: short\n" " arg3: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
@ -136,7 +145,8 @@ check(A.func3default.__doc__,
"\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"
" ----------\n"
" e: A *\n" " e: A *\n"
" arg3: short\n" " arg3: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
@ -145,7 +155,8 @@ check(A.func3default.__doc__,
"\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"
"----------\n"
"e: A *\n" "e: A *\n"
"arg3: short\n" "arg3: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
@ -153,7 +164,8 @@ check(A.func3default.__doc__,
"\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"
"----------\n"
"e: A *\n" "e: A *\n"
"arg3: short\n" "arg3: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
@ -185,7 +197,8 @@ 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"
" ----------\n"
" e: A *\n" " e: A *\n"
" arg2: short\n" " arg2: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
@ -193,7 +206,8 @@ check(A.func2static.__doc__,
"\n" "\n"
" func2static(e, arg2, hello) -> int\n" " func2static(e, arg2, hello) -> int\n"
"\n" "\n"
" Parameters:\n" " Parameters\n"
" ----------\n"
" e: A *\n" " e: A *\n"
" arg2: short\n" " arg2: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
@ -202,7 +216,8 @@ 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"
"----------\n"
"e: A *\n" "e: A *\n"
"arg2: short\n" "arg2: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
@ -210,7 +225,8 @@ check(A.func2static.__doc__,
"\n" "\n"
"func2static(e, arg2, hello) -> int\n" "func2static(e, arg2, hello) -> int\n"
"\n" "\n"
"Parameters:\n" "Parameters\n"
"----------\n"
"e: A *\n" "e: A *\n"
"arg2: short\n" "arg2: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
@ -221,7 +237,8 @@ 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"
" ----------\n"
" e: A *\n" " e: A *\n"
" arg2: short\n" " arg2: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
@ -229,7 +246,8 @@ check(A.func3static.__doc__,
"\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"
" ----------\n"
" e: A *\n" " e: A *\n"
" arg2: short\n" " arg2: short\n"
" hello: int tuple[2]\n" " hello: int tuple[2]\n"
@ -238,7 +256,8 @@ 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"
"----------\n"
"e: A *\n" "e: A *\n"
"arg2: short\n" "arg2: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
@ -246,7 +265,8 @@ check(A.func3static.__doc__,
"\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"
"----------\n"
"e: A *\n" "e: A *\n"
"arg2: short\n" "arg2: short\n"
"hello: int tuple[2]\n" "hello: int tuple[2]\n"
@ -268,7 +288,8 @@ 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"
"----------\n"
"self: A *\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"
"----------\n"
"self: A *\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,7 +316,8 @@ 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"
" ----------\n"
" a: special comment for parameter a\n" " a: special comment for parameter a\n"
" b: another special comment for parameter b\n" " b: another special comment for parameter b\n"
" h: enum Hola\n" " h: enum Hola\n"
@ -305,7 +328,8 @@ 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"
" ----------\n"
" a: special comment for parameter a\n" " a: special comment for parameter a\n"
" b: another special comment for parameter b\n" " b: another special comment for parameter b\n"
" h: enum Hola\n" " h: enum Hola\n"

15
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,7 +1799,8 @@ 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
pdocs = NewString("\nParameters\n----------\n");
Printf(pdocs, "%s\n", pdoc); Printf(pdocs, "%s\n", pdoc);
} }
// Write the function annotation // Write the function 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) {