doxypypy
doxypypy copied to clipboard
Feneric
Documentation of the modules
To document a module (as a namespace) I need to write in the file:
## @package name.of.module
#
# description
#
I would like to be able to write only docstrings and that they are directly translated (as in your examples). The best would be not to rewrite @package but I can live with it. So basically
""" description
"""
Oh, and I'm using Python3
If it is any consolation, you can do:
""" @package name.of.module
Here is a brief description.
This is my detailed description
that is so long that
it spans several lines
"""
I ended to do something else:
## Brief text here
## @namespace package_name.module_name
While doxypypy generates something like this instead:
## @brief Brief text here
To the OP: using @package is not good, since it is cumulative and applies to all modules of a package. A Python module is treated as a namespace for Doxygen, at least if you choose OPTIMIZE_OUTPUT_JAVA, which seems recommended for Python.
I feel this may be an issue with Doxygen by the way, since it even should be:
##! @namespace package_name.module_name
## @brief Brief text here
Instead of:
## Brief text here
## @namespace package_name.module_name
… which I guessed as an accident
Oh, I just got a better and clean way!
Just put something like this right after the module’s docstring:
## @namespace midi.channel_events
That’s enough. So doxypypy may just have to be tweaked to generate it automatically. I will try to find a way to it when I will have time.
Note the namespace used must exactly much the one inferred by Doxygen, or else it will generate an empty namespace (that is, an empty module) of the wrong name in the same package.
More on the above:
This works:
## @namespace foo.bar
""" Quickly about `foo.bar`
More …
"""
But this does not work:
## @namespace foo.bar
""" Quickly about `foo.bar`
More …
"""
If the @namespace special command comes before the @brief comment block (what Doxypypy turns the docstring into), then there must not be any empty lines between the two. I don’t know if it’s a Doxygen feature or a bug.
When the @namespace special command comes after the comment block, there may or may not be empty lines, both works.
This works:
""" Quickly about `foo.bar`
More …
"""
## @namespace foo.bar
This works too:
""" Quickly about `foo.bar`
More …
"""
## @namespace foo.bar
+1 for this issue -- doxypypy should definitely automatically add the namespace to the module-level pydoc.
