This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
Re: RFC: use markdown in libstdc++ Doxygen comments
On 01/05/19 13:13 -0400, Ed Smith-Rowland wrote:
On 5/1/19 5:11 AM, Jonathan Wakely wrote:
This is something I've been thinking about for a while now, and as
it's stage 1 I'd like to discuss it.
Doxygen comments support a few different forms of markup:
// You can refer to @c code or @p parameters like this.
// You can refer to \c code or \p parameters like this.
// You can refer to <code>code</code> or <i>parameters</i> like this.
I've used <tt>two words</tt>.? Blech.
Yeah, as I mentioned in the follow-up mail you can also use Doxygen's
@code two words @endcode but that's even worse than HTML/XML IMHO.
For a while now Doxygen has supported Markdown, and I think that's a
much better solution. It gives far more control over the generated
HTML than the @c or \c tags, without the visual clutter of HTML tags.
The example above from std::sort would become:
?*? Sorts the elements in the range `[__first, __last)` in ascending
order,
?*? such that for each iterator `i` in the range `[__first, __last-1)`,
?*? `*(i+1) < *i` is false.
Nice.
Does anybody object to this change?
This is a good idea.
I'll probably have to keep my maths in the old format ;-). But almost
Yes, I was just looking at that yesterday. I think fragments of LaTeX
like this are fine:
* and the ratio
* @f[
* \frac{|f - f_{test}|}{|f_{test}|}
* @f]
I see no need to change that. The generated output for this is very
nice, and it's the right way to express it IMHO.
everything else should be md.
Thanks for the input.