On Sep 6, 2012, at 8:56 , Petr Prikryl <prik...@skil.cz> wrote: >> Vaclav Petras wrote... > ... >>> Petr Prikryl wrote... >>>> 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. >>> [...]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. > > This should be answered by Dimitri. Anyway, I would be for adding > another configuration settings that says how the docstrings should > be treated. The user can choose in the case.
This is an undocumented feature rather than a bug. (see initTriDoubleQuoteBlock() and initTriSingleQuoteBlock() in pyscanner.l) It could be put behind an option, but I don't think that is really needed: who will start their sentence with an exclamation mark by accident? An option to treat all docstrings as special comments might be useful. > >>> 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 What is the status of this Python Enhancement Proposal? reStructuredText is like Markdown (which doxygen now supports), and for which I had to so quite some work to make it co-exist with the native doxygen markup. Adding yet another slightly incompatible markup language could prove to be difficult. > > The Doxyfile setting should be designed the way that allows to > add a reStructuredText parser in future. But the Doxygen filters > can also be used for the purpose. So, this is the question for > the designer. I am sure that Dimitri would like to have a good > analysis of the problem if anything should be "fixed". Indeed. Regards, Dimitri ------------------------------------------------------------------------------ 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
