RFC: use markdown in libstdc++ Doxygen comments

[Jonathan Wakely]

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.