Commit 85188943 authored by Manuel Günther's avatar Manuel Günther
Browse files

Improved alignment of contructors.

parent 5f0d116b
......@@ -171,6 +171,17 @@ To generate a properly aligned function documentation, you can use::
.. note::
Please assure that you define this variable as ``static``.
.. note::
If you want to document a member function of a class, you should use set fourth boolean option to true.
This is required since the default python class member documentation is indented four more spaces, which we need to balance::
static xbob::extension::FunctionDoc member_function_description(
"function_name",
"Short function description",
"Optional long function description",
true
);
Using this object, you can add several parts of the function that need documentation:
1. ``description.add_prototype("variable1, variable2", "return1, return2");`` can be used to add function definitions (i.e., ways how to use your function).
......@@ -181,6 +192,15 @@ Using this object, you can add several parts of the function that need documenta
3. ``description.add_return("return1", "datatype", "Return value description");`` should be defined for each return value that you have used in the prototypes.
.. note::
All these functions return a reference to the object, so that you can use them in line, e.g.::
static auto description = xbob::extension::FunctionDoc(...)
.add_prototype(...)
.add_parameter(...)
.add_return(...)
;
Finally, when binding you function, you can use:
a) ``description.name()`` to get the name of the function
......@@ -237,6 +257,10 @@ The shortest way to get a proper class documentation is::
.. note::
The second parameter ``""`` in ``add_prototype`` prevents the output type (which otherwise defaults to ``"None"``) to be written.
.. note::
For constructor documentations, there is no need to declare them as member functions.
This is done automatically for you.
Currently, the ClassDoc allows to highlight member functions or variables at the beginning of the class documentation.
This highlighting is still under development and might not work as expected.
......
......@@ -529,6 +529,8 @@ inline xbob::extension::ClassDoc& xbob::extension::ClassDoc::add_constructor(
throw std::runtime_error("The class documentation can have only a single constructor documentation");
}
constructor.push_back(constructor_documentation);
// since we indent the constructor documentation ourselves, we don't need to consider it to be a member function.
constructor.back().is_member = false;
#endif // XBOB_SHORT_DOCSTRINGS
return *this;
}
......@@ -564,7 +566,7 @@ inline char* xbob::extension::ClassDoc::doc(
description = _align(class_description, 0, alignment) + "\n";
if (!constructor.empty()){
description += "\n" + _align("**Constructor Documentation:**", 0, alignment) + "\n\n";
description += constructor.front().doc(alignment, 2) + std::string("\n");
description += constructor.front().doc(alignment, 4) + std::string("\n");
}
description += "\n" + _align("**Class Members:**", 0, alignment) + "\n\n";
if (!highlighted_functions.empty()){
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment