Re: [PATCH v2] libstdc++: improve documentation for bits/stl_function.h [PR51539]

[Jonathan Wakely <jwakely@redhat.com>]

On Wed, 18 Aug 2021 at 13:49, Jonathan Wakely <jwakely@redhat.com> wrote:
>
> On Tue, 17 Aug 2021 at 21:39, Krzysztof Żelechowski
> <giecrilj@stegny.2a.pl> wrote:
> >    template<typename _Tp>
> >      struct greater : public binary_function<_Tp, _Tp, bool>
> >      {
> > +       /// Tests whether parameter 1 is greater (`operator>`) than parameter
> > 2.
>
> I don't like the use of "parameter 1" and "parameter 2" here. They
> have names, we can just say `x` and `y`.
>
> And if we're doing that, I wonder why we don't just say "@returns `x >
> y`" which is precise and correct. It's not accurate to say `operator>`
> because there is no such function for fundamental types, e.g.
> std::greater<int>()(1, 2) does not use a function called `operator>`
> it uses the built-in > operator. There is a distinction, and the way
> you're documenting it is not strictly correct.
>
> We could do that for every operator() that you're documenting.
> Personally I think that would be much better (and it's also how
> cppreference.com describes these).

Maybe the right compromise is to not mention `operator>` at all, but
combine prose and code like this:

/// Tests whether the first parameter is greater than the second
/// @returns `x > y`