Message ID | c076cbde-0ef5-9e92-8c82-4b6e5d765fea@gmail.com |
---|---|
State | Not applicable |
Headers |
Return-Path: <libc-alpha-bounces@sourceware.org> X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id E1CC13857C5A; Tue, 4 Aug 2020 09:40:47 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E1CC13857C5A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1596534047; bh=iav4m4B008hsmECdE+mTLyA574h7Kp4I+f2tTKPt8HI=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=UaGH2I73yjIuF3Q45Pt/oV7j1t2pjTGyX6KEnEjtzrBTPioc0xNvtAqBxK20aSEZx vazED0icoIGQajXnMUe1gxNKiv/gPwXT+y+bnRF56RycHhl7QriW02nZwshY1HhT/O Njv3TOMS3WnVLbE3PT7+vMfPQCHCbY3nu37pDdhY= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wm1-x32a.google.com (mail-wm1-x32a.google.com [IPv6:2a00:1450:4864:20::32a]) by sourceware.org (Postfix) with ESMTPS id C72883857C57 for <libc-alpha@sourceware.org>; Tue, 4 Aug 2020 09:40:44 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org C72883857C57 Received: by mail-wm1-x32a.google.com with SMTP id g8so2054956wmk.3 for <libc-alpha@sourceware.org>; Tue, 04 Aug 2020 02:40:44 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:to:cc:from:subject:message-id:date:user-agent :mime-version:content-language:content-transfer-encoding; bh=iav4m4B008hsmECdE+mTLyA574h7Kp4I+f2tTKPt8HI=; b=rbrYw+iwRcDskhCRQXVMdz5lGKBPt/5XHOkG8S07aPz72dapfb3/ZwH5B+hCcgDR9O /F/5xG1IV1PZInVsr/Mo3rgD6ZRAWFSWO0KSB4XQJwJNnOgh6S+bU5oJ3Kjx7wiRsTk8 bwQHTze9LJ1wrcc9Jsn/x82Ql7BT9aLBWGUJMY1R/KTiKDe2RJ3yXkis+rvIknZT3SeI 0pAbnfaeYRQdNdV/WuMHds71SGmOEAS7pp+RwtfLKkInQSmXEGDapGtVrxQoUoAKmuV0 uC+kBNtnRuQ1MpckehMeOYDEeogJFniM2ikzgKy7qoG/6lOQ6FE9AJMU7Q9ybo6pJ/4k 1F+w== X-Gm-Message-State: AOAM532lSJmqJjaUS2WU10IbrI6T4SKUMZ43mgL4Xj9aaQULLOAXExpB xVPcrlP21eFAW8rZP8KLumPpG4xL X-Google-Smtp-Source: ABdhPJytxhBUp7jXNFjvQhJAY5+kdk1iluvp4CbYBEN3AYNMQUHm+pl0L0hGUC4V2ybDJG+PMNgsvw== X-Received: by 2002:a1c:c910:: with SMTP id f16mr1851902wmb.82.1596534043592; Tue, 04 Aug 2020 02:40:43 -0700 (PDT) Received: from [192.168.0.160] ([93.115.133.118]) by smtp.gmail.com with ESMTPSA id z67sm3759615wmg.28.2020.08.04.02.40.42 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 04 Aug 2020 02:40:42 -0700 (PDT) To: linux-man@vger.kernel.org Subject: [patch] queue.3: Comment out text for functions not in glibc (related: 6559169cac) Message-ID: <c076cbde-0ef5-9e92-8c82-4b6e5d765fea@gmail.com> Date: Tue, 4 Aug 2020 11:40:41 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-10.4 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list <libc-alpha.sourceware.org> List-Unsubscribe: <https://sourceware.org/mailman/options/libc-alpha>, <mailto:libc-alpha-request@sourceware.org?subject=unsubscribe> List-Archive: <https://sourceware.org/pipermail/libc-alpha/> List-Post: <mailto:libc-alpha@sourceware.org> List-Help: <mailto:libc-alpha-request@sourceware.org?subject=help> List-Subscribe: <https://sourceware.org/mailman/listinfo/libc-alpha>, <mailto:libc-alpha-request@sourceware.org?subject=subscribe> From: Alejandro Colomar via Libc-alpha <libc-alpha@sourceware.org> Reply-To: Alejandro Colomar <colomar.6.4.3@gmail.com> Cc: libc-alpha@sourceware.org Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" <libc-alpha-bounces@sourceware.org> |
Series |
queue.3: Comment out text for functions not in glibc (related: 6559169cac)
|
|
Commit Message
Alejandro Colomar
Aug. 4, 2020, 9:40 a.m. UTC
=========== DESCRIPTION =========== I'm documenting ``CIRCLEQ_*`` macros in queue.3. While writing this, I noticed that the documentation for some types of queues/lists talked about swapping contents of two lists, but only for some of them. I then found that those macros (``*_SWAP``) don't exist in my system (Debian), but exist in BSD, and I also found that a previous commit (6559169cac) commented out a lot of the *_SWAP macros documentation, but not all, and the reason was that they were not present on glibc. I checked that I didn't have any of the *_SWAP macros on my glibc, so I think this is probably that the commit simply forgot to comment some of them. ======= TESTING ======= I tun ``sudo make`` and then visualized the man page with ``man 3 queue``, and the changes looked good. I also noticed that the subsection ``Tail queue example`` contents were wrong, as they contained calls to CIRCLEQ_* macros. I will address that in a future patch, before I submit the patch documenting CIRCLEQ_*.
Comments
Hello Alejandro, On 8/4/20 11:40 AM, Alejandro Colomar wrote: > =========== > DESCRIPTION > =========== > > I'm documenting ``CIRCLEQ_*`` macros in queue.3. While writing this, I > noticed that the documentation for some types of queues/lists talked > about swapping contents of two lists, but only for some of them. I then > found that those macros (``*_SWAP``) don't exist in my system (Debian), > but exist in BSD, and I also found that a previous commit (6559169cac) > commented out a lot of the *_SWAP macros documentation, but not all, and > the reason was that they were not present on glibc. > > I checked that I didn't have any of the *_SWAP macros on my glibc, so I > think this is probably that the commit simply forgot to comment some of > them. > > ======= > TESTING > ======= > > I tun ``sudo make`` and then visualized the man page with > ``man 3 queue``, and the changes looked good. > > I also noticed that the subsection ``Tail queue example`` contents were > wrong, as they contained calls to CIRCLEQ_* macros. I will address that > in a future patch, before I submit the patch documenting CIRCLEQ_*. > > ________________________________________________________________________ > P.S.: I'd like to know, as my previous patch was oddly reformatted by > my mailer, if you can see it correctly this time. I changed some, > configuration, so I hope it is fine. All pretty good this time. I applied your patch. Two things to note: * There was some superfluous whitespace at the end of some of the changed lines. By chance, that got automatically fixed up. No big problem, but it generates a bit of unnecessary noise when applying the patch [1] * I added the following on your hehalf: Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> Thanks, Michael > ===== > PATCH > ===== > > From 2282ba2397e6ac7dca4cc09dfcb92ac524718f27 Mon Sep 17 00:00:00 2001 > From: Alejandro Colomar <colomar.6.4.3@gmail.com> > Date: Sun, 26 Jul 2020 23:36:42 +0200 > Subject: [PATCH] queue.3: Comment out text for functions not in glibc > (related: 6559169cac) > > --- > man3/queue.3 | 26 +++++++++++++------------- > 1 file changed, 13 insertions(+), 13 deletions(-) > > diff --git a/man3/queue.3 b/man3/queue.3 > index 00e4b1958..ff1f42f3a 100644 > --- a/man3/queue.3 > +++ b/man3/queue.3 > @@ -110,8 +110,8 @@ > .Nm TAILQ_LAST , > .Nm TAILQ_NEXT , > .Nm TAILQ_PREV , > -.Nm TAILQ_REMOVE , > -.Nm TAILQ_SWAP > +.Nm TAILQ_REMOVE > +.\" .Nm TAILQ_SWAP > .Nd implementations of singly-linked lists, singly-linked tail queues, > lists and tail queues > .Sh SYNOPSIS > @@ -172,7 +172,7 @@ lists and tail queues > .Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" > .\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" > .Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" > -.Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY > NAME" > +.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" > "LIST_ENTRY NAME" > .\" > .Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY > NAME" > .Fn TAILQ_EMPTY "TAILQ_HEAD *head" > @@ -197,7 +197,7 @@ lists and tail queues > .Fn TAILQ_NEXT "TYPE *elm" "TAILQ_ENTRY NAME" > .Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME" > .Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" > -.Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" > "TAILQ_ENTRY NAME" > +.\" .Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" > "TAILQ_ENTRY NAME" > .\" > .Sh DESCRIPTION > These macros define and operate on four types of data structures: > @@ -213,8 +213,8 @@ Insertion of a new entry after any element in the list. > O(1) removal of an entry from the head of the list. > .It > Forward traversal through the list. > -.It > -Swapping the contents of two lists. > +.\" .It > +.\" Swapping the contents of two lists. > .El > .Pp > Singly-linked lists are the simplest of the four data structures > @@ -1157,13 +1157,13 @@ The macro > removes the element > .Fa elm > from the tail queue. > -.Pp > -The macro > -.Nm TAILQ_SWAP > -swaps the contents of > -.Fa head1 > -and > -.Fa head2 . > +.\" .Pp > +.\" The macro > +.\" .Nm TAILQ_SWAP > +.\" swaps the contents of > +.\" .Fa head1 > +.\" and > +.\" .Fa head2 . > .Ss Tail queue example > .Bd -literal > TAILQ_HEAD(tailhead, entry) head = >
diff --git a/man3/queue.3 b/man3/queue.3 index 00e4b1958..ff1f42f3a 100644 --- a/man3/queue.3 +++ b/man3/queue.3 @@ -110,8 +110,8 @@ .Nm TAILQ_LAST , .Nm TAILQ_NEXT , .Nm TAILQ_PREV , -.Nm TAILQ_REMOVE , -.Nm TAILQ_SWAP +.Nm TAILQ_REMOVE +.\" .Nm TAILQ_SWAP .Nd implementations of singly-linked lists, singly-linked tail queues, lists and tail queues .Sh SYNOPSIS @@ -172,7 +172,7 @@ lists and tail queues .Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" .\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" .Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" +.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" .\"