pep257 & numpydoc conforming docstrings
This commit is contained in:
xantares
William S Fulton
parent
263847e704
commit
92328a2016
4 changed files with 156 additions and 124 deletions
|
|
@ -5273,8 +5273,8 @@ def function_name(*args, **kwargs):
|
|||
|
||||
<p>
|
||||
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
|
||||
code will be:
|
||||
documentation is generated for each parameter using <a href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpydoc</a> style.
|
||||
Using the previous example, the generated code will be:
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
|
|
@ -5283,11 +5283,12 @@ def function_name(*args, **kwargs):
|
|||
"""
|
||||
function_name(x, y, foo=None, bar=None) -> bool
|
||||
|
||||
Parameters:
|
||||
x: int
|
||||
y: int
|
||||
foo: Foo *
|
||||
bar: Bar *
|
||||
Parameters
|
||||
----------
|
||||
x: int
|
||||
y: int
|
||||
foo: Foo *
|
||||
bar: Bar *
|
||||
|
||||
"""
|
||||
...
|
||||
|
|
@ -5318,11 +5319,12 @@ def function_name(*args, **kwargs):
|
|||
"""
|
||||
function_name(x, y, foo=None, bar=None) -> bool
|
||||
|
||||
Parameters:
|
||||
x (C++ type: int) -- Input x dimension
|
||||
y: int
|
||||
foo: Foo *
|
||||
bar: Bar *
|
||||
Parameters
|
||||
----------
|
||||
x (C++ type: int) -- Input x dimension
|
||||
y: int
|
||||
foo: Foo *
|
||||
bar: Bar *
|
||||
|
||||
"""
|
||||
</pre>
|
||||
|
|
@ -5341,11 +5343,12 @@ def function_name(*args, **kwargs):
|
|||
"""
|
||||
function_name(int x, int y, Foo foo=None, Bar bar=None) -> bool
|
||||
|
||||
Parameters:
|
||||
x: int
|
||||
y: int
|
||||
foo: Foo *
|
||||
bar: Bar *
|
||||
Parameters
|
||||
----------
|
||||
x: int
|
||||
y: int
|
||||
foo: Foo *
|
||||
bar: Bar *
|
||||
|
||||
"""
|
||||
...
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
%module(docstring="hello") autodoc
|
||||
%module(docstring="hello.") autodoc
|
||||
|
||||
%feature("autodoc");
|
||||
|
||||
|
|
@ -27,7 +27,7 @@
|
|||
%feature("autodoc","2") A::variable_c; // extended
|
||||
%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 {
|
||||
|
||||
|
|
|
|||
|
|
@ -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 = True
|
||||
|
||||
check(A.__doc__, "Proxy of C++ A class", "::A")
|
||||
check(A.funk.__doc__, "just a string")
|
||||
check(A.__doc__, "Proxy of C++ A class.", "::A")
|
||||
check(A.funk.__doc__, "just a string.")
|
||||
check(A.func0.__doc__,
|
||||
"func0(self, arg2, hello) -> int",
|
||||
"func0(arg2, hello) -> int")
|
||||
|
|
@ -35,17 +35,19 @@ check(A.func2.__doc__,
|
|||
"\n"
|
||||
" func2(self, arg2, hello) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"\n"
|
||||
" ",
|
||||
"\n"
|
||||
"func2(arg2, hello) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"arg2: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"\n"
|
||||
""
|
||||
)
|
||||
|
|
@ -53,17 +55,19 @@ check(A.func3.__doc__,
|
|||
"\n"
|
||||
" func3(A self, short arg2, Tuple hello) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"\n"
|
||||
" ",
|
||||
"\n"
|
||||
"func3(short arg2, Tuple hello) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"arg2: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"\n"
|
||||
""
|
||||
)
|
||||
|
|
@ -92,35 +96,39 @@ check(A.func2default.__doc__,
|
|||
"\n"
|
||||
" func2default(self, e, arg3, hello, f=2) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
"\n"
|
||||
" func2default(self, e, arg3, hello) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"\n"
|
||||
" ",
|
||||
"\n"
|
||||
"func2default(e, arg3, hello, f=2) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"e: A *\n"
|
||||
"arg3: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"f: double\n"
|
||||
"\n"
|
||||
"func2default(e, arg3, hello) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"e: A *\n"
|
||||
"arg3: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"\n"
|
||||
""
|
||||
)
|
||||
|
|
@ -128,35 +136,39 @@ check(A.func3default.__doc__,
|
|||
"\n"
|
||||
" func3default(A self, A e, short arg3, Tuple hello, double f=2) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
"\n"
|
||||
" func3default(A self, A e, short arg3, Tuple hello) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"\n"
|
||||
" ",
|
||||
"\n"
|
||||
"func3default(A e, short arg3, Tuple hello, double f=2) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"e: A *\n"
|
||||
"arg3: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"f: double\n"
|
||||
"\n"
|
||||
"func3default(A e, short arg3, Tuple hello) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg3: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"e: A *\n"
|
||||
"arg3: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"\n"
|
||||
""
|
||||
)
|
||||
|
|
@ -185,35 +197,39 @@ check(A.func2static.__doc__,
|
|||
"\n"
|
||||
" func2static(e, arg2, hello, f=2) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
"\n"
|
||||
" func2static(e, arg2, hello) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"\n"
|
||||
" ",
|
||||
"\n"
|
||||
"func2static(e, arg2, hello, f=2) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"e: A *\n"
|
||||
"arg2: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"f: double\n"
|
||||
"\n"
|
||||
"func2static(e, arg2, hello) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"e: A *\n"
|
||||
"arg2: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"\n"
|
||||
""
|
||||
)
|
||||
|
|
@ -221,35 +237,39 @@ check(A.func3static.__doc__,
|
|||
"\n"
|
||||
" func3static(A e, short arg2, Tuple hello, double f=2) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
"\n"
|
||||
" func3static(A e, short arg2, Tuple hello) -> int\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"\n"
|
||||
" ",
|
||||
"\n"
|
||||
"func3static(A e, short arg2, Tuple hello, double f=2) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
" f: double\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"e: A *\n"
|
||||
"arg2: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"f: double\n"
|
||||
"\n"
|
||||
"func3static(A e, short arg2, Tuple hello) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" e: A *\n"
|
||||
" arg2: short\n"
|
||||
" hello: int tuple[2]\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"e: A *\n"
|
||||
"arg2: short\n"
|
||||
"hello: int tuple[2]\n"
|
||||
"\n"
|
||||
""
|
||||
)
|
||||
|
|
@ -268,8 +288,9 @@ if sys.version_info[0:2] > (2, 4):
|
|||
"\n"
|
||||
"A_variable_c_get(self) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" self: A *\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"self: A *\n"
|
||||
"\n",
|
||||
"A.variable_c"
|
||||
)
|
||||
|
|
@ -277,14 +298,15 @@ if sys.version_info[0:2] > (2, 4):
|
|||
"\n"
|
||||
"A_variable_d_get(A self) -> int\n"
|
||||
"\n"
|
||||
"Parameters:\n"
|
||||
" self: A *\n"
|
||||
"Parameters\n"
|
||||
"----------\n"
|
||||
"self: A *\n"
|
||||
"\n",
|
||||
"A.variable_d"
|
||||
)
|
||||
|
||||
check(B.__doc__,
|
||||
"Proxy of C++ B class",
|
||||
"Proxy of C++ B class.",
|
||||
"::B"
|
||||
)
|
||||
check(C.__init__.__doc__, "__init__(self, a, b, h) -> C", None, skip)
|
||||
|
|
@ -294,10 +316,11 @@ check(E.__init__.__doc__,
|
|||
"\n"
|
||||
" __init__(self, a, b, h) -> E\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" a: special comment for parameter a\n"
|
||||
" b: another special comment for parameter b\n"
|
||||
" h: enum Hola\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" a: special comment for parameter a\n"
|
||||
" b: another special comment for parameter b\n"
|
||||
" h: enum Hola\n"
|
||||
"\n"
|
||||
" ", None, skip
|
||||
)
|
||||
|
|
@ -305,10 +328,11 @@ check(F.__init__.__doc__,
|
|||
"\n"
|
||||
" __init__(F self, int a, int b, Hola h) -> F\n"
|
||||
"\n"
|
||||
" Parameters:\n"
|
||||
" a: special comment for parameter a\n"
|
||||
" b: another special comment for parameter b\n"
|
||||
" h: enum Hola\n"
|
||||
" Parameters\n"
|
||||
" ----------\n"
|
||||
" a: special comment for parameter a\n"
|
||||
" b: another special comment for parameter b\n"
|
||||
" h: enum Hola\n"
|
||||
"\n"
|
||||
" ", None, skip
|
||||
)
|
||||
|
|
|
|||
|
|
@ -799,7 +799,11 @@ public:
|
|||
Swig_register_filebyname("python", f_shadow);
|
||||
|
||||
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);
|
||||
mod_docstring = NULL;
|
||||
}
|
||||
|
|
@ -1795,8 +1799,9 @@ public:
|
|||
Append(doc, name);
|
||||
if (pdoc) {
|
||||
if (!pdocs)
|
||||
pdocs = NewString("\nParameters:\n");
|
||||
Printf(pdocs, " %s\n", pdoc);
|
||||
// numpydoc style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
|
||||
pdocs = NewString("\nParameters\n----------\n");
|
||||
Printf(pdocs, "%s\n", pdoc);
|
||||
}
|
||||
// Write the function annotation
|
||||
if (func_annotation)
|
||||
|
|
@ -1892,9 +1897,9 @@ public:
|
|||
Delete(rname);
|
||||
} else {
|
||||
if (CPlusPlus) {
|
||||
Printf(doc, "Proxy of C++ %s class", real_classname);
|
||||
Printf(doc, "Proxy of C++ %s class.", real_classname);
|
||||
} 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)) {
|
||||
String *str = docstring(n, AUTODOC_CLASS, tab4);
|
||||
if (str && Len(str))
|
||||
Printv(f_shadow, tab4, str, "\n", NIL);
|
||||
Printv(f_shadow, tab4, str, "\n\n", NIL);
|
||||
}
|
||||
|
||||
if (!modern) {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue