This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
RFC: use markdown in libstdc++ Doxygen comments
- From: Jonathan Wakely <jwakely at redhat dot com>
- To: libstdc++ at gcc dot gnu dot org
- Date: Wed, 1 May 2019 10:11:47 +0100
- Subject: RFC: use markdown in libstdc++ Doxygen comments
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?
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index a62eeffa393..c3a4ba7e547 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -282,7 +282,7 @@ EXTENSION_MAPPING = no_extension=C++ .h=C++ .tcc=C++ .hpp=C++
# case of backward compatibilities issues.
# The default value is: YES.
-MARKDOWN_SUPPORT = NO
+MARKDOWN_SUPPORT = YES
# When enabled doxygen tries to link words that correspond to documented
# classes, or namespaces to their corresponding documentation. Such a link can
diff --git a/libstdc++-v3/include/bits/stl_algo.h b/libstdc++-v3/include/bits/stl_algo.h
index b50c642f0e6..fad30fbe549 100644
--- a/libstdc++-v3/include/bits/stl_algo.h
+++ b/libstdc++-v3/include/bits/stl_algo.h
@@ -401,24 +401,24 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __last1 End of range to search.
* @param __first2 Start of sequence to match.
* @param __last2 End of sequence to match.
- * @return The last iterator @c i in the range
- * @p [__first1,__last1-(__last2-__first2)) such that @c *(i+N) ==
- * @p *(__first2+N) for each @c N in the range @p
- * [0,__last2-__first2), or @p __last1 if no such iterator exists.
+ * @return The last iterator `i` in the range
+ * `[__first1, __last1-(__last2-__first2))` such that `*(i+N) ==
+ * *(__first2+N)` for each `N` in the range
+ * `[0, __last2-__first2)`, or `__last1` if no such iterator exists.
*
- * Searches the range @p [__first1,__last1) for a sub-sequence that
- * compares equal value-by-value with the sequence given by @p
- * [__first2,__last2) and returns an iterator to the __first
- * element of the sub-sequence, or @p __last1 if the sub-sequence
+ * Searches the range `[__first1, __last1)` for a sub-sequence that
+ * compares equal value-by-value with the sequence given by
+ * `[__first2, __last2)` and returns an iterator to the first
+ * element of the sub-sequence, or `__last1` if the sub-sequence
* is not found. The sub-sequence will be the last such
- * subsequence contained in [__first1,__last1).
+ * subsequence contained in `[__first1,__last1)`.
*
- * Because the sub-sequence must lie completely within the range @p
- * [__first1,__last1) it must start at a position less than @p
- * __last1-(__last2-__first2) where @p __last2-__first2 is the
+ * Because the sub-sequence must lie completely within the range
+ * `[__first1, __last1)` it must start at a position less than
+ * `__last1-(__last2-__first2)` where `__last2-__first2` is the
* length of the sub-sequence. This means that the returned
- * iterator @c i will be in the range @p
- * [__first1,__last1-(__last2-__first2))
+ * iterator `i` will be in the range
+ * `[__first1, __last1-(__last2-__first2))`
*/
template<typename _ForwardIterator1, typename _ForwardIterator2>
inline _ForwardIterator1
@@ -448,25 +448,25 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __first2 Start of sequence to match.
* @param __last2 End of sequence to match.
* @param __comp The predicate to use.
- * @return The last iterator @c i in the range @p
- * [__first1,__last1-(__last2-__first2)) such that @c
- * predicate(*(i+N), @p (__first2+N)) is true for each @c N in the
- * range @p [0,__last2-__first2), or @p __last1 if no such iterator
+ * @return The last iterator `i` in the range
+ * `[__first1, __last1-(__last2-__first2))` such that
+ * `__comp(*(i+N), (__first2+N))` is `true` for each `N` in the
+ * range `[0, __last2-__first2)`, or `__last1` if no such iterator
* exists.
*
- * Searches the range @p [__first1,__last1) for a sub-sequence that
- * compares equal value-by-value with the sequence given by @p
- * [__first2,__last2) using comp as a predicate and returns an
- * iterator to the first element of the sub-sequence, or @p __last1
+ * Searches the range `[__first1, __last1)` for a sub-sequence that
+ * compares equal value-by-value with the sequence given by
+ * `[__first2, __last2)` using comp as a predicate and returns an
+ * iterator to the first element of the sub-sequence, or `__last1`
* if the sub-sequence is not found. The sub-sequence will be the
- * last such subsequence contained in [__first,__last1).
+ * last such subsequence contained in `[__first, __last1)`.
*
- * Because the sub-sequence must lie completely within the range @p
- * [__first1,__last1) it must start at a position less than @p
- * __last1-(__last2-__first2) where @p __last2-__first2 is the
+ * Because the sub-sequence must lie completely within the range
+ * `[__first1, __last1)` it must start at a position less than
+ * `__last1-(__last2-__first2)` where `__last2-__first2` is the
* length of the sub-sequence. This means that the returned
- * iterator @c i will be in the range @p
- * [__first1,__last1-(__last2-__first2))
+ * iterator `i` will be in the range
+ * `[__first1, __last1-(__last2-__first2))`
*/
template<typename _ForwardIterator1, typename _ForwardIterator2,
typename _BinaryPredicate>
@@ -500,8 +500,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __pred A predicate.
* @return True if the check is true, false otherwise.
*
- * Returns true if @p __pred is true for each element in the range
- * @p [__first,__last), and false otherwise.
+ * Returns `true` if `__pred` is `true` for each element in the range
+ * `[__first, __last)`, and `false` otherwise.
*/
template<typename _InputIterator, typename _Predicate>
inline bool
@@ -517,8 +517,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __pred A predicate.
* @return True if the check is true, false otherwise.
*
- * Returns true if @p __pred is false for each element in the range
- * @p [__first,__last), and false otherwise.
+ * Returns `true` if `__pred` is `false` for each element in the range
+ * `[__first, __last)`, and `false` otherwise.
*/
template<typename _InputIterator, typename _Predicate>
inline bool
@@ -534,9 +534,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __pred A predicate.
* @return True if the check is true, false otherwise.
*
- * Returns true if an element exists in the range @p
- * [__first,__last) such that @p __pred is true, and false
- * otherwise.
+ * Returns `true` if an element exists in the range `[__first, __last)`
+ * such that `__pred` is `true`, and `false` otherwise.
*/
template<typename _InputIterator, typename _Predicate>
inline bool
@@ -550,8 +549,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __first An input iterator.
* @param __last An input iterator.
* @param __pred A predicate.
- * @return The first iterator @c i in the range @p [__first,__last)
- * such that @p __pred(*i) is false, or @p __last if no such iterator exists.
+ * @return The first iterator `i` in the range `[__first, __last)`
+ * such that `__pred(*i)` is `false`, or `__last` if no such iterator exists.
*/
template<typename _InputIterator, typename _Predicate>
inline _InputIterator
@@ -573,8 +572,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __first An input iterator.
* @param __last An input iterator.
* @param __pred A predicate.
- * @return True if the range @p [__first,__last) is partioned by @p __pred,
- * i.e. if all elements that satisfy @p __pred appear before those that
+ * @return `true` if the range `[__first, __last)` is partioned by `__pred`,
+ * i.e. if all elements that satisfy `__pred` appear before those that
* do not.
*/
template<typename _InputIterator, typename _Predicate>
@@ -595,8 +594,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __first An iterator.
* @param __last Another iterator.
* @param __pred A predicate.
- * @return An iterator @p mid such that @p all_of(__first, mid, __pred)
- * and @p none_of(mid, __last, __pred) are both true.
+ * @return An iterator `mid` such that `all_of(__first, mid, __pred)`
+ * and `none_of(mid, __last, __pred)` are both `true`.
*/
template<typename _ForwardIterator, typename _Predicate>
_ForwardIterator
@@ -660,9 +659,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __value The value to be removed.
* @return An iterator designating the end of the resulting sequence.
*
- * Copies each element in the range @p [__first,__last) not equal
- * to @p __value to the range beginning at @p __result.
- * remove_copy() is stable, so the relative order of elements that
+ * Copies each element in the range `[__first, __last)` not equal
+ * to `__value` to the range beginning at `__result`.
+ * `remove_copy()` is stable, so the relative order of elements that
* are copied is unchanged.
*/
template<typename _InputIterator, typename _OutputIterator, typename _Tp>
@@ -691,10 +690,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __pred A predicate.
* @return An iterator designating the end of the resulting sequence.
*
- * Copies each element in the range @p [__first,__last) for which
- * @p __pred returns false to the range beginning at @p __result.
+ * Copies each element in the range `[__first, __last)` for which
+ * `__pred` returns `false` to the range beginning at `__result`.
*
- * remove_copy_if() is stable, so the relative order of elements that are
+ * `remove_copy_if` is stable, so the relative order of elements that are
* copied is unchanged.
*/
template<typename _InputIterator, typename _OutputIterator,
@@ -725,10 +724,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __pred A predicate.
* @return An iterator designating the end of the resulting sequence.
*
- * Copies each element in the range @p [__first,__last) for which
- * @p __pred returns true to the range beginning at @p __result.
+ * Copies each element in the range `[__first, __last)` for which
+ * `__pred` returns true to the range beginning at `__result`.
*
- * copy_if() is stable, so the relative order of elements that are
+ * `copy_if` is stable, so the relative order of elements that are
* copied is unchanged.
*/
template<typename _InputIterator, typename _OutputIterator,
@@ -789,7 +788,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __result An output iterator.
* @return result+n.
*
- * This inline function will boil down to a call to @c memmove whenever
+ * This inline function will boil down to a call to `memmove` whenever
* possible. Failing that, if random access iterators are passed, then the
* loop count will be known (and therefore a candidate for compiler
* optimizations such as unrolling).
@@ -818,9 +817,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __pred A predicate.
* @return A pair designating the ends of the resulting sequences.
*
- * Copies each element in the range @p [__first,__last) for which
- * @p __pred returns true to the range beginning at @p out_true
- * and each element for which @p __pred returns false to @p __out_false.
+ * Copies each element in the range `[__first, __last)` for which
+ * `__pred` returns `true` to the range beginning at `__out_true`
+ * and each element for which `__pred` returns `false` to `__out_false`.
*/
template<typename _InputIterator, typename _OutputIterator1,
typename _OutputIterator2, typename _Predicate>
@@ -882,13 +881,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __value The value to be removed.
* @return An iterator designating the end of the resulting sequence.
*
- * All elements equal to @p __value are removed from the range
- * @p [__first,__last).
+ * All elements equal to `__value` are removed from the range
+ * `[__first, __last)`.
*
- * remove() is stable, so the relative order of elements that are
+ * `remove` is stable, so the relative order of elements that are
* not removed is unchanged.
*
- * Elements between the end of the resulting sequence and @p __last
+ * Elements between the end of the resulting sequence and `__last`
* are still present, but their value is unspecified.
*/
template<typename _ForwardIterator, typename _Tp>
@@ -915,13 +914,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @param __pred A predicate.
* @return An iterator designating the end of the resulting sequence.
*
- * All elements for which @p __pred returns true are removed from the range
- * @p [__first,__last).
+ * All elements for which `__pred` returns `true` are removed from the range
+ * `[__first, __last)`.
*
- * remove_if() is stable, so the relative order of elements that are
+ * `remove_if` is stable, so the relative order of elements that are
* not removed is unchanged.
*
- * Elements between the end of the resulting sequence and @p __last
+ * Elements between the end of the resulting sequence and `__last`
* are still present, but their value is unspecified.
*/
template<typename _ForwardIterator, typename _Predicate>
@@ -985,9 +984,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* Removes all but the first element from each group of consecutive
* values that compare equal.
- * unique() is stable, so the relative order of elements that are
+ * `unique` is stable, so the relative order of elements that are
* not removed is unchanged.
- * Elements between the end of the resulting sequence and @p __last
+ * Elements between the end of the resulting sequence and `__last`
* are still present, but their value is unspecified.
*/
template<typename _ForwardIterator>
@@ -1014,10 +1013,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @return An iterator designating the end of the resulting sequence.
*
* Removes all but the first element from each group of consecutive
- * values for which @p __binary_pred returns true.
- * unique() is stable, so the relative order of elements that are
+ * values for which `__binary_pred` returns `true`.
+ * `unique` is stable, so the relative order of elements that are
* not removed is unchanged.
- * Elements between the end of the resulting sequence and @p __last
+ * Elements between the end of the resulting sequence and `__last`
* are still present, but their value is unspecified.
*/
template<typename _ForwardIterator, typename _BinaryPredicate>
@@ -4023,9 +4022,9 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __first A forward iterator.
* @param __last A forward iterator.
* @param __binary_pred A binary predicate.
- * @return The first iterator @c i such that @c i and @c i+1 are both
- * valid iterators in @p [__first,__last) and such that
- * @p __binary_pred(*i,*(i+1)) is true, or @p __last if no such iterator
+ * @return The first iterator `i` such that `i` and `i+1` are both
+ * valid iterators in `[__first, __last)` and such that
+ * `__binary_pred(*i,*(i+1))` is `true`, or `__last` if no such iterator
* exists.
*/
template<typename _ForwardIterator, typename _BinaryPredicate>
@@ -4050,8 +4049,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __first An input iterator.
* @param __last An input iterator.
* @param __value The value to be counted.
- * @return The number of iterators @c i in the range @p [__first,__last)
- * for which @c *i == @p __value
+ * @return The number of iterators `i` in the range `[__first, __last)`
+ * for which `*i == __value`
*/
template<typename _InputIterator, typename _Tp>
inline typename iterator_traits<_InputIterator>::difference_type
@@ -4073,8 +4072,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __first An input iterator.
* @param __last An input iterator.
* @param __pred A predicate.
- * @return The number of iterators @c i in the range @p [__first,__last)
- * for which @p __pred(*i) is true.
+ * @return The number of iterators `i` in the range `[__first, __last)`
+ * for which `__pred(*i)` is `true`.
*/
template<typename _InputIterator, typename _Predicate>
inline typename iterator_traits<_InputIterator>::difference_type
@@ -4799,12 +4798,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last Another iterator.
* @return Nothing.
*
- * 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.
+ * 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`.
*
* The relative ordering of equivalent elements is not preserved, use
- * @p stable_sort() if this is needed.
+ * `stable_sort()` if this is needed.
*/
template<typename _RandomAccessIterator>
inline void
@@ -4829,12 +4828,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __comp A comparison functor.
* @return Nothing.
*
- * Sorts the elements in the range @p [__first,__last) in ascending order,
- * such that @p __comp(*(i+1),*i) is false for every iterator @e i in the
- * range @p [__first,__last-1).
+ * Sorts the elements in the range `[__first, __last)` in ascending order,
+ * such that `__comp(*(i+1), *i)` is false for every iterator `i` in the
+ * range `[__first, __last-1)`.
*
* The relative ordering of equivalent elements is not preserved, use
- * @p stable_sort() if this is needed.
+ * `stable_sort()` if this is needed.
*/
template<typename _RandomAccessIterator, typename _Compare>
inline void
@@ -4889,11 +4888,11 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @return An iterator pointing to the first element <em>not less
* than</em> @e val.
*
- * Merges the ranges @p [__first1,__last1) and @p [__first2,__last2) into
- * the sorted range @p [__result, __result + (__last1-__first1) +
- * (__last2-__first2)). Both input ranges must be sorted, and the
+ * Merges the ranges `[__first1, __last1)` and `[__first2, __last2)` into
+ * the sorted range `[__result, __result + (__last1-__first1) +
+ * (__last2-__first2))`. Both input ranges must be sorted, and the
* output range must not overlap with either of the input ranges.
- * The sort is @e stable, that is, for equivalent elements in the
+ * The sort is *stable*, that is, for equivalent elements in the
* two ranges, elements from the first range will always come
* before elements from the second.
*/
@@ -4936,11 +4935,11 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @return An iterator pointing to the first element "not less
* than" @e val.
*
- * Merges the ranges @p [__first1,__last1) and @p [__first2,__last2) into
- * the sorted range @p [__result, __result + (__last1-__first1) +
- * (__last2-__first2)). Both input ranges must be sorted, and the
+ * Merges the ranges `[__first1, __last1)` and `[__first2, __last2)` into
+ * the sorted range `[__result, __result + (__last1-__first1) +
+ * (__last2-__first2))`. Both input ranges must be sorted, and the
* output range must not overlap with either of the input ranges.
- * The sort is @e stable, that is, for equivalent elements in the
+ * The sort is *stable*, that is, for equivalent elements in the
* two ranges, elements from the first range will always come
* before elements from the second.
*
@@ -5002,14 +5001,14 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last Another iterator.
* @return Nothing.
*
- * Sorts the elements in the range @p [__first,__last) in ascending order,
- * such that for each iterator @p i in the range @p [__first,__last-1),
- * @p *(i+1)<*i is false.
+ * 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`.
*
* The relative ordering of equivalent elements is preserved, so any two
- * elements @p x and @p y in the range @p [__first,__last) such that
- * @p x<y is false and @p y<x is false will have the same relative
- * ordering after calling @p stable_sort().
+ * elements `x` and `y` in the range `[__first, __last)` such that
+ * `x < y` is `false` and `y < x` is `false` will have the same relative
+ * ordering after calling `stable_sort()`.
*/
template<typename _RandomAccessIterator>
inline void
@@ -5036,14 +5035,14 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __comp A comparison functor.
* @return Nothing.
*
- * Sorts the elements in the range @p [__first,__last) in ascending order,
- * such that for each iterator @p i in the range @p [__first,__last-1),
- * @p __comp(*(i+1),*i) is false.
+ * Sorts the elements in the range `[__first, __last)` in ascending order,
+ * such that for each iterator `i` in the range `[__first, __last-1)`,
+ * `__comp(*(i+1), *i)` is `false`.
*
* The relative ordering of equivalent elements is preserved, so any two
- * elements @p x and @p y in the range @p [__first,__last) such that
- * @p __comp(x,y) is false and @p __comp(y,x) is false will have the same
- * relative ordering after calling @p stable_sort().
+ * elements `x` and `y` in the range `[__first, __last)` such that
+ * `__comp(x,y)` is `false` and `__comp(y, x)` is `false` will have the same
+ * relative ordering after calling `stable_sort()`.
*/
template<typename _RandomAccessIterator, typename _Compare>
inline void
@@ -5159,8 +5158,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* This operation iterates over both ranges, copying elements present in
* each range in order to the output range. Iterators increment for each
* range. When the current element of one range is less than the other
- * according to @p __comp, that element is copied and the iterator advanced.
- * If an equivalent element according to @p __comp is contained in both
+ * according to `__comp`, that element is copied and the iterator advanced.
+ * If an equivalent element according to `__comp` is contained in both
* ranges, the element from the first range is copied and both ranges
* advance. The output range may not overlap either input range.
*/
@@ -5279,8 +5278,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* This operation iterates over both ranges, copying elements present in
* both ranges in order to the output range. Iterators increment for each
* range. When the current element of one range is less than the other
- * according to @p __comp, that iterator advances. If an element is
- * contained in both ranges according to @p __comp, the element from the
+ * according to `__comp`, that iterator advances. If an element is
+ * contained in both ranges according to `__comp`, the element from the
* first range is copied and both ranges advance. The output range may not
* overlap either input range.
*/
@@ -5533,9 +5532,9 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* This operation iterates over both ranges, copying elements present in
* one range but not the other in order to the output range. Iterators
* increment for each range. When the current element of one range is less
- * than the other according to @p comp, that element is copied and the
+ * than the other according to `__comp`, that element is copied and the
* iterator advances. If an element is contained in both ranges according
- * to @p __comp, no elements are copied and both ranges advance. The output
+ * to `__comp`, no elements are copied and both ranges advance. The output
* range may not overlap either input range.
*/
template<typename _InputIterator1, typename _InputIterator2,