[snip]
>
> ... 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.
>
Yes, it can be even changed (e.g. by using %s). In this case Doxygen
really don't have any chance to deal with. Except for substituting %s
for variable name or something similar.
> 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.
This is clear for me, docstrings (""" """) are for API, so I want to
get them to have in API html documentation generated by Doxygen.
Comments (#) are for describing implementation details which are
useful when I'm changing implementation (I don't need them in
Doxygen). So as I wrote before I use """.
>
>> 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.
I hope that it is not a bug I want my comments to be processed by
Doxygen as rich comments not only verbatim text. It could be done by
exclamation mark (as it is now) or some settings in Doxygen
configuration file.
>
> 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.
Interesting idea. This would mean that you either cannot use Doxygen
(or at least doxygen markup) for Python at all or that Doxygen should
support reStructuredText. Because, according to PEP 287,
reStructuredText is the the standard way how to format Python
docstrings.
So in my opinion there is one bug
* ! is not mentioned in documentation
and two enhancements
* turn on markup interpretation in Python docstrings from Doxyfile
* support at least basic reStructuredText because it is in PEP 287
Any opinions?
Vaclav
[1] http://www.python.org/dev/peps/pep-0287/
------------------------------------------------------------------------------
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
