From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTP id D1DD5385C419 for ; Wed, 18 Aug 2021 12:58:57 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D1DD5385C419 Received: from mail-wm1-f71.google.com (mail-wm1-f71.google.com [209.85.128.71]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-498-QVg6S_kDN2yuRz1-bfNsFw-1; Wed, 18 Aug 2021 08:58:56 -0400 X-MC-Unique: QVg6S_kDN2yuRz1-bfNsFw-1 Received: by mail-wm1-f71.google.com with SMTP id m13-20020a7bcf2d000000b002e6cd9941a9so2219345wmg.1 for ; Wed, 18 Aug 2021 05:58:55 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=Jb9Y2IzvW8iOtTWP2NbnY/AJwcCMRxexe3EwG1lxVVY=; b=GwNPKDbLy2VudOMWLDkOpXk966dDLxpKQOkXWoyf4nomstQ2y+S7gZdoHs10RwSM0n ZA+PnW/uacMYNZR0StuhCRXSJhW6kfC5VWtqC8gRO6lGMDCL5wFiptCpDrJ/T6FYxCEP 8xNbOWGHpQLlDUeryQ1uzK1B1d91lQWVEwlRV4eEU6M2UjaREs2hSux2Ujyy+ITpTKbS IVSmbgbzXls3aJdex+NozHnYpU71Od/XqWCnqWqV6DPcQlaD05mNEC9RPbF/A2F3ciZ/ gp7uVIV7PWBP4JgPn4tZernaHwTBYZpB7Qnt0x0mR/KMar5FhCxkDB+vIBdlzTyKkDj1 IaoA== X-Gm-Message-State: AOAM531DIiy4SViPQrA1wqjt+Pa0sdrqKQvmh4znxI62F4t1U6ZLNBfk U/3J5xrWlepjWttW3j+7GpzQyXvd8WqO1IGIjnsaxPmtDBC8Ne9YGIh2ZkMYnmIIoZJU+CMPaf9 s57/N/ui1tDkQdeD/TOLAqKYp374ceOE= X-Received: by 2002:a5d:51cb:: with SMTP id n11mr10469787wrv.221.1629291534889; Wed, 18 Aug 2021 05:58:54 -0700 (PDT) X-Google-Smtp-Source: ABdhPJzJKO8fl7bzVSnYMIGkustKkKpEsZprS0eJWFSDK9w4Bw04UP4M3EgdxJBCV5T582o69tdUKHfnIadzpbeIFmo= X-Received: by 2002:a5d:51cb:: with SMTP id n11mr10469772wrv.221.1629291534723; Wed, 18 Aug 2021 05:58:54 -0700 (PDT) MIME-Version: 1.0 References: <2880466.YWZaH7Zrci@localhost.localdomain> In-Reply-To: From: Jonathan Wakely Date: Wed, 18 Aug 2021 13:58:43 +0100 Message-ID: Subject: Re: [PATCH v2] libstdc++: improve documentation for bits/stl_function.h [PR51539] To: =?UTF-8?Q?Krzysztof_=C5=BBelechowski?= Cc: gcc Patches , "libstdc++" X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: libstdc++@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++ mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 18 Aug 2021 12:59:07 -0000 On Wed, 18 Aug 2021 at 13:49, Jonathan Wakely wrote: > > On Tue, 17 Aug 2021 at 21:39, Krzysztof =C5=BBelechowski > wrote: > > template > > struct greater : public binary_function<_Tp, _Tp, bool> > > { > > + /// Tests whether parameter 1 is greater (`operator>`) than par= ameter > > 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()(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`