queue.3: Comment out text for functions not in glibc (related: 6559169cac)

Message ID c076cbde-0ef5-9e92-8c82-4b6e5d765fea@gmail.com
State New
Headers show
Series
  • queue.3: Comment out text for functions not in glibc (related: 6559169cac)
Related show

Commit Message

Vitaly Buka via Libc-alpha Aug. 4, 2020, 9:40 a.m.
.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 =
-- 
2.27.0

Comments

Vitaly Buka via Libc-alpha Aug. 4, 2020, 12:48 p.m. | #1
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 =

> 



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Patch

===========
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.

=====
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"
  .\"