RFC: use markdown in libstdc++ Doxygen comments

[Jonathan Wakely]

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.

Currently we use the first form. This has some problems, the main one
being that there's no delimiter for the @c or \c tags, so only the
next "word" (for some value of word decided by Doxygen) gets marked
up. We try to deal with this by removing all spaces from expressions,
e.g. 

  *  Sorts the elements in the range @p [__first,__last) in ascending order,
  *  such that for each iterator @e i in the range @p [__first,__last-1),  
  *  *(i+1)<*i is false.

But this doesn't actually work. As you can see at
https://gcc.gnu.org/onlinedocs/gcc-8.3.0/libstdc++/api/a01482.html#ga4ea03048647c50ea7cbdd5da30e82755
the generated HTML for this is:

  <p>Sorts the elements in the range <code></code>[__first,__last)
  in ascending order, such that for each iterator <em>i</em> in the range
  <code></code>[__first,__last-1), *(i+1)<*i is false.</p>

This is poor. We might as well not bother using @c and @p at all.

I *really* want to avoid using HTML or XML tags in the Doxygen
comments, because although the generated HTML looks good, they make it
much more difficult to read the actual comments in the original source
code.

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.

This produces:

  <p>Sorts the elements in the range <code>[__first, __last)</code>
  in ascending order, such that for each iterator <code>i</code> in the range
  <code>[__first, __last-1)</code>, <code>*(i+1) < *i</code> is false.</p>

Admittedly I'm a fan of Markdown, but I think this is a clear
improvement for the original comments in the source and for the
generated HTML (yes I know there are some ambiguities in the Markdown
spec, and several different flavours of Markdown with slightly
different features, but in practice that rarely matters ... and it's
still less ambiguous than Doxygen markup!)

I've attached a patch that turns on Markdown support in our Doxygen
config file, and starts to reformat comments in <bits/stl_algo.h>.

There's no need for a flag day where all comments are converted to
markdown, because the existing markup still works the same as it
always did. We could just start using Markdown in new comments, and
optionally reformat existing comments when touching a function.

Does anybody object to this change?


-------------- next part --------------
A non-text attachment was scrubbed...
Name: patch.txt
Type: text/x-patch
Size: 24288 bytes
Desc: not available
URL: <http://gcc.gnu.org/pipermail/libstdc++/attachments/20190501/30252109/attachment.bin>