reStructured text in Doxygen comments without \rst and \endrst

[vitaut]

It would be nice to be able to write Doxygen comments in reStructuredText without the need to wrap everything in \rst and \endrst directives. So I'd like to open this issue to discuss possible ways to do this. Can it be done in Breathe alone or does it require anything from the Doxygen side (e.g. to keep the comment formatting intact)?

[michaeljones]

Hey, interesting idea. Happy to explore it. I can't do any development or hands on research this week but here are some points:

• What does RST test in comments look like in the xml files? Does it look parse-able as rst or perhaps we could reconstruct valid rst from it?
• Does Doxygen have any flags to ask it not to process the comments at all to help preserve the rst?
• What does this mean for the work that Doxygen does auto-link class name and types in the comments?

Just some thoughts, Michael

[vitaut]

I've just done a small experiment and here's the Doxygen XML output with \rst/\endrst:

    <detaileddescription>
<para><verbatim>embed:rst
A string reference. It can be constructed from a C string or
``std::string``.

You can use one of the following typedefs for common character types:

+------------+-------------------------+
| Type       | Definition              |
+============+=========================+
| StringRef  | BasicStringRef&lt;char&gt;    |
+------------+-------------------------+
| WStringRef | BasicStringRef&lt;wchar_t&gt; |
+------------+-------------------------+

This class is most useful as a parameter type to allow passing
different types of strings to a function, for example::

  template&lt;typename... Args&gt;
  std::string format(StringRef format, const Args &amp; ... args);

  format(&quot;{}&quot;, 42);
  format(std::string(&quot;{}&quot;), 42);
</verbatim> </para>    </detaileddescription>

and here's without:

<para>A string reference. </para>    </briefdescription>
    <detaileddescription>
<para>It can be constructed from a C string or <computeroutput>std::string</computeroutput>.</para><para>You can use one of the following typedefs for common character types:</para><para>+---------<mdash/>+----------------------<mdash/>+ | Type | Definition | +============+=========================+ | StringRef | BasicStringRef&lt;char&gt; | +---------<mdash/>+----------------------<mdash/>+ | WStringRef | BasicStringRef&lt;wchar_t&gt; | +---------<mdash/>+----------------------<mdash/>+</para><para>This class is most useful as a parameter type to allow passing different types of strings to a function, for example::</para><para>template&lt;typename... Args&gt; std::string format(StringRef format, const Args &amp; ... args);</para><para>format(&quot;{}&quot;, 42); format(std::string(&quot;{}&quot;), 42); </para>    </detaileddescription>

As you can see in the second case the formatting is completely messed up. The main problem is that the newlines are removed and I don't think it's possible to recover the original formatting.

So we get to your second question and I don't know the answer to it yet.

As for the autolinking, I don't think there is one in \rst blocks right now.

Cheers, Victor

[michaeljones]

You're right about the auto-linking. That is one of the flaws. And I'd agree that that output looks pretty useless as far as reconstructing the original. Does the xml output contain any information about the line numbers? I think there is information about the function body but maybe not the lines of the comment itself.

If we knew the lines of the comment itself, we might be able to go and parse the original file and render the rst ourselves. Quite a bit of effort though.

[vitaut]

Yes, the XML output contains line numbers so it's possible to locate comments in the original sources. I've also asked on the Doxygen users group if it is possible to preserve formatting without using \verbatim: http://sourceforge.net/p/doxygen/mailman/message/32656827/. Let's see what they say.

[vermeeren]

@vitaut I know this is a very long time ago, but did you receive any information from the developers?

Myself I think this could not be properly implemented without some changes in Doxygen itself, but maybe I am wrong.

Also this is the last issue when it comes to issue tracker checking and cleanup! :)