There is a kind of shisophrenia related to Python docstrings...
> I'm confused about python docstrings and how Doxygen handles them.
> By docstring I really mean this """ """. I don't want to use ##
> comments for documenting API in Python.
... It is because Python docstrings are actually part of the code.
They are string literals that are accessible in runtime. However,
they are also used to generate a documentation.
But Python allows also comments. Then, there are two ways of
documenting a Python code.
> When I use only simple docstring, I get docstring content in verbatim
> as stated in manual [1] (example [2]).
> """My comment.
>
> More here.
> """
Thinking about Python as about one of the languages that can
be documented via Python, the docstrings are part of the code.
The Python comments with # are not parts of the code. They should
rather contain the comments for a developer.
If you think about Doxygen, it is rather the tool for developers.
You can use it for producing the user documentation.
> But when I put exclamation mark at the beginning of docstring, Doxygen
> commands are interpreted as for other languages or ## comments (example
> [3]).
> """!My comment.
>
> More here.
> """
This could be a kind of experiment. Or it is simply a bug.
The exclamation mark at the beginning of a comment marks
the block as the one that explicitly says "this is to be
processed by Doxygen as the documentation of the code".
It is likely that interpreting the exclamation mark in a docstring
is an unwanted side effect.
In my opinion, if one wants to use Doxygen for documentation
of a project, that fact should not affect the documented project.
In other words, the Doxygen related details should not be visible
when running a Python program.
Regards,
Petr
------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
