RFC: use markdown in libstdc++ Doxygen comments

Ed Smith-Rowland via libstdc++ libstdc++@gcc.gnu.org
Wed May 1 17:13:00 GMT 2019


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.
> 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 
everything else should be md.

Ed




More information about the Libstdc++ mailing list