On 6 September 2012 21:18, Dimitri van Heesch <dimi...@stack.nl> wrote: > > 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. > I would prefer the option. I wouldn't put exclamation mark at the beginning of sentence (not sure about Spanish friends) but it is highly probable that I will forgot that.
>> >>>> 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? The PEP 287 [1] status is Active [2] and type Informational [3]. I'm not familiar with Python PEP but according to [2]: "Some Informational and Process PEPs may also have a status of "Active" if they are never meant to be completed." > 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. > Definitively reStructuredText and Markdown cannot be mixed. And maybe it is not necessary to mix reStructuredText with Doxygen markup either. Now I'm thinking about using reStructuredText only for Python docstrings. There are some unclear areas like syntax for function parameters [4] or links/references to other compounds, however for documenting functions, classes and modules only part of reStructuredText is needed. I would like to see some option in Doxyfile how to treat python docstrings, e.g. INTERPRET_PYTHON_DOCSTRINGS_AS with possible values: verbatim (default) | Doxygen&Markdown (today's exclamation mark) | reStructuredText About the things which should be considered, compatibly with Sphinx and not breaking Breathe would be probably appreciated, from my user point of view. Vaclav [1] http://www.python.org/dev/peps/pep-0287/ [2] http://www.python.org/dev/peps/pep-0001/#pep-review-resolution [3] http://www.python.org/dev/peps/pep-0001/#pep-types [4] http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html ------------------------------------------------------------------------------ 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
