list, set, oset, map, omap: avoid imperative voice in documentation

list, set, oset, map, omap: avoid imperative voice in documentation

[Bruno Haible]

Each time I read the function specifications in gl_list.h, the use of
imperative voice ("Return true if ...") feels wrong. "Returns true if ..." is
the correct grammar.

Why? Because imperative form is used to instruct someone. In the context
of the documentation of a function, there are two "who"s involved:
  - (A) the programmer who implemented the function,
  - (B) the programmer who wants to invoke the function.
Thus, the only valid use of imperative form in this context is an
instruction for (B), for example: "Don't pass a negative value as argument."

Things are different inside the function definition: Here, (B) is not
supposed to look. The two "who"s here are:
  - (A) the programmer who implemented the function,
  - (C) the machine which executes the code.
Here, an imperative voice from (A) to (C) is reasonable.

The Python people get this wrong [1]. Probably because they put the
specification of a function at the beginning of the function definition,
and thus blur the distinction between documentation and function definition.

[1] https://www.python.org/dev/peps/pep-0257/


2020-02-02  Bruno Haible  <bruno@clisp.org>

	list, set, oset, map, omap: Avoid imperative voice in documentation.
	* lib/gl_list.h: Use descriptive sentences instead of imperative voice
	in the specification of functions.
	* lib/gl_set.h: Likewise.
	* lib/gl_oset.h: Likewise.
	* lib/gl_map.h: Likewise.
	* lib/gl_omap.h: Likewise.
	* lib/gl_*.h: Likewise.

diff --git a/lib/gl_anyavltree_list2.h b/lib/gl_anyavltree_list2.h
index 4148296..3cb1fcd 100644
--- a/lib/gl_anyavltree_list2.h
+++ b/lib/gl_anyavltree_list2.h
@@ -19,9 +19,9 @@
 
 /* -------------------------- gl_list_t Data Type -------------------------- */
 
-/* Create a subtree for count >= 1 elements.
+/* Creates a subtree for count >= 1 elements.
    Its height is h where 2^(h-1) <= count <= 2^h - 1.
-   Return NULL upon out-of-memory.  */
+   Returns NULL upon out-of-memory.  */
 static gl_list_node_t
 create_subtree_with_contents (size_t count, const void **contents)
 {
@@ -138,7 +138,7 @@ gl_tree_nx_create (gl_list_implementation_t implementation,
   return NULL;
 }
 
-/* Ensure the tree is balanced, after an insertion or deletion operation.
+/* Ensures the tree is balanced, after an insertion or deletion operation.
    The height of NODE is incremented by HEIGHT_DIFF (1 or -1).
    PARENT = NODE->parent.  (NODE can also be NULL.  But PARENT is non-NULL.)
    Rotation operations are performed starting at PARENT (not NODE itself!).  */
diff --git a/lib/gl_anyhash2.h b/lib/gl_anyhash2.h
index a720d5e..ac70b45 100644
--- a/lib/gl_anyhash2.h
+++ b/lib/gl_anyhash2.h
@@ -22,7 +22,7 @@
 
 #include "gl_anyhash_primes.h"
 
-/* Resize the hash table with a new estimated size.  */
+/* Resizes the hash table with a new estimated size.  */
 static void
 hash_resize (CONTAINER_T container, size_t estimate)
 {
@@ -70,7 +70,7 @@ hash_resize (CONTAINER_T container, size_t estimate)
   return;
 }
 
-/* Resize the hash table if needed, after CONTAINER_COUNT (container) was
+/* Resizes the hash table if needed, after CONTAINER_COUNT (container) was
    incremented.  */
 static void
 hash_resize_after_add (CONTAINER_T container)
diff --git a/lib/gl_anyhash_primes.h b/lib/gl_anyhash_primes.h
index a696206..c8f2d8d 100644
--- a/lib/gl_anyhash_primes.h
+++ b/lib/gl_anyhash_primes.h
@@ -74,7 +74,7 @@ static const size_t primes[] =
     SIZE_MAX /* sentinel, to ensure the search terminates */
   };
 
-/* Return a suitable prime >= ESTIMATE.  */
+/* Returns a suitable prime >= ESTIMATE.  */
 static size_t
 next_prime (size_t estimate)
 {
diff --git a/lib/gl_anyrbtree_list2.h b/lib/gl_anyrbtree_list2.h
index f57168d..f14eda0 100644
--- a/lib/gl_anyrbtree_list2.h
+++ b/lib/gl_anyrbtree_list2.h
@@ -19,7 +19,7 @@
 
 /* -------------------------- gl_list_t Data Type -------------------------- */
 
-/* Create a subtree for count >= 1 elements.
+/* Creates a subtree for count >= 1 elements.
    Its black-height bh is passed as argument, with
    2^bh - 1 <= count <= 2^(bh+1) - 1.  bh == 0 implies count == 1.
    Its height is h where 2^(h-1) <= count <= 2^h - 1.
@@ -153,7 +153,7 @@ gl_tree_nx_create (gl_list_implementation_t implementation,
   return NULL;
 }
 
-/* Rotate left a subtree.
+/* Rotates left a subtree.
 
                          B                         D
                        /   \                     /   \
@@ -161,7 +161,7 @@ gl_tree_nx_create (gl_list_implementation_t implementation,
                             / \               / \
                            C   E             A   C
 
-   Change the tree structure, update the branch sizes.
+   Changes the tree structure, updates the branch sizes.
    The caller must update the colors and register D as child of its parent.  */
 static gl_list_node_t
 rotate_left (gl_list_node_t b_node, gl_list_node_t d_node)
@@ -187,7 +187,7 @@ rotate_left (gl_list_node_t b_node, gl_list_node_t d_node)
   return d_node;
 }
 
-/* Rotate right a subtree.
+/* Rotates right a subtree.
 
                            D                     B
                          /   \                 /   \
@@ -195,7 +195,7 @@ rotate_left (gl_list_node_t b_node, gl_list_node_t d_node)
                       / \                           / \
                      A   C                         C   E
 
-   Change the tree structure, update the branch sizes.
+   Changes the tree structure, updates the branch sizes.
    The caller must update the colors and register B as child of its parent.  */
 static gl_list_node_t
 rotate_right (gl_list_node_t b_node, gl_list_node_t d_node)
@@ -221,7 +221,7 @@ rotate_right (gl_list_node_t b_node, gl_list_node_t d_node)
   return b_node;
 }
 
-/* Ensure the tree is balanced, after an insertion operation.
+/* Ensures the tree is balanced, after an insertion operation.
    Also assigns node->color.
    parent is the given node's parent, known to be non-NULL.  */
 static void
@@ -345,7 +345,7 @@ rebalance_after_add (gl_list_t list, gl_list_node_t node, gl_list_node_t parent)
     }
 }
 
-/* Ensure the tree is balanced, after a deletion operation.
+/* Ensures the tree is balanced, after a deletion operation.
    CHILD was a grandchild of PARENT and is now its child.  Between them,
    a black node was removed.  CHILD is also black, or NULL.
    (CHILD can also be NULL.  But PARENT is non-NULL.)  */
diff --git a/lib/gl_anytree_list1.h b/lib/gl_anytree_list1.h
index f3c15c1..457df31 100644
--- a/lib/gl_anytree_list1.h
+++ b/lib/gl_anytree_list1.h
@@ -28,7 +28,7 @@ typedef struct
 /* A stack used for iterating across the elements.  */
 typedef iterstack_item_t iterstack_t[MAXHEIGHT];
 
-/* Free a non-empty subtree recursively.
+/* Frees a non-empty subtree recursively.
    This function is recursive and therefore not very fast.  */
 static void
 free_subtree (gl_list_node_t node)
diff --git a/lib/gl_anytree_list2.h b/lib/gl_anytree_list2.h
index 51358af..c5a67db 100644
--- a/lib/gl_anytree_list2.h
+++ b/lib/gl_anytree_list2.h
@@ -136,7 +136,7 @@ gl_tree_previous_node (gl_list_t list, gl_list_node_t node)
   return node;
 }
 
-/* Return the node at the given position < gl_tree_size (list).  */
+/* Returns the node at the given position < gl_tree_size (list).  */
 static gl_list_node_t _GL_ATTRIBUTE_PURE
 node_at (gl_list_node_t root, size_t position)
 {
diff --git a/lib/gl_anytreehash_list1.h b/lib/gl_anytreehash_list1.h
index 8e8fecd..aba45d6 100644
--- a/lib/gl_anytreehash_list1.h
+++ b/lib/gl_anytreehash_list1.h
@@ -28,7 +28,7 @@ struct gl_multiple_nodes
    gl_list_node_impl.  */
 #define MULTIPLE_NODES_MAGIC  (void *) -1
 
-/* Return the position of the given node in the tree.  */
+/* Returns the position of the given node in the tree.  */
 static size_t
 node_position (gl_list_node_t node)
 {
@@ -76,7 +76,7 @@ compare_position_threshold (const void *x, const void *threshold)
   return (position >= (uintptr_t)threshold);
 }
 
-/* Return the first element of a non-empty ordered set of nodes.  */
+/* Returns the first element of a non-empty ordered set of nodes.  */
 static gl_list_node_t
 gl_oset_first (gl_oset_t set)
 {
@@ -89,7 +89,7 @@ gl_oset_first (gl_oset_t set)
   return (gl_list_node_t) first;
 }
 
-/* Add a node to the hash table structure.
+/* Adds a node to the hash table structure.
    If duplicates are allowed, this function performs in average time
    O((log n)^2): gl_oset_nx_add may need to add an element to an ordered set
    of size O(n), needing O(log n) comparison function calls.  The comparison
@@ -178,7 +178,7 @@ add_to_bucket (gl_list_t list, gl_list_node_t new_node)
 #define add_to_bucket(list,node) \
     __builtin_expect ((add_to_bucket) (list, node), 0)
 
-/* Remove a node from the hash table structure.
+/* Removes a node from the hash table structure.
    If duplicates are allowed, this function performs in average time
    O((log n)^2): gl_oset_remove may need to remove an element from an ordered
    set of size O(n), needing O(log n) comparison function calls.  The
@@ -257,9 +257,9 @@ remove_from_bucket (gl_list_t list, gl_list_node_t old_node)
     }
 }
 
-/* Build up the hash table during initialization: Store all the nodes of
+/* Builds up the hash table during initialization: Stores all the nodes of
    list->root in the hash table.
-   Return 0 upon success, -1 upon out-of-memory.  */
+   Returns 0 upon success, -1 upon out-of-memory.  */
 static int
 add_nodes_to_buckets (gl_list_t list)
 {
diff --git a/lib/gl_avltree_ordered.h b/lib/gl_avltree_ordered.h
index 70f3356..014886c 100644
--- a/lib/gl_avltree_ordered.h
+++ b/lib/gl_avltree_ordered.h
@@ -57,7 +57,7 @@ struct CONTAINER_IMPL
    this would exceed the address space of the machine.  */
 #define MAXHEIGHT 83
 
-/* Ensure the tree is balanced, after an insertion or deletion operation.
+/* Ensures the tree is balanced, after an insertion or deletion operation.
    The height of NODE is incremented by HEIGHT_DIFF (1 or -1).
    PARENT = NODE->parent.  (NODE can also be NULL.  But PARENT is non-NULL.)
    Rotation operations are performed starting at PARENT (not NODE itself!).  */
diff --git a/lib/gl_list.h b/lib/gl_list.h
index 35dd43d..39d1440 100644
--- a/lib/gl_list.h
+++ b/lib/gl_list.h
@@ -130,7 +130,7 @@ typedef const struct gl_list_implementation * gl_list_implementation_t;
 
 #if 0 /* Unless otherwise specified, these are defined inline below.  */
 
-/* Create an empty list.
+/* Creates an empty list.
    IMPLEMENTATION is one of GL_ARRAY_LIST, GL_CARRAY_LIST, GL_LINKED_LIST,
    GL_AVLTREE_LIST, GL_RBTREE_LIST, GL_LINKEDHASH_LIST, GL_AVLTREEHASH_LIST,
    GL_RBTREEHASH_LIST.
@@ -145,14 +145,14 @@ extern gl_list_t gl_list_create_empty (gl_list_implementation_t implementation,
                                        gl_listelement_hashcode_fn hashcode_fn,
                                        gl_listelement_dispose_fn dispose_fn,
                                        bool allow_duplicates);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_t gl_list_nx_create_empty (gl_list_implementation_t implementation,
                                           gl_listelement_equals_fn equals_fn,
                                           gl_listelement_hashcode_fn hashcode_fn,
                                           gl_listelement_dispose_fn dispose_fn,
                                           bool allow_duplicates);
 
-/* Create a list with given contents.
+/* Creates a list with given contents.
    IMPLEMENTATION is one of GL_ARRAY_LIST, GL_CARRAY_LIST, GL_LINKED_LIST,
    GL_AVLTREE_LIST, GL_RBTREE_LIST, GL_LINKEDHASH_LIST, GL_AVLTREEHASH_LIST,
    GL_RBTREEHASH_LIST.
@@ -170,7 +170,7 @@ extern gl_list_t gl_list_create (gl_list_implementation_t implementation,
                                  gl_listelement_dispose_fn dispose_fn,
                                  bool allow_duplicates,
                                  size_t count, const void **contents);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_t gl_list_nx_create (gl_list_implementation_t implementation,
                                     gl_listelement_equals_fn equals_fn,
                                     gl_listelement_hashcode_fn hashcode_fn,
@@ -178,17 +178,17 @@ extern gl_list_t gl_list_nx_create (gl_list_implementation_t implementation,
                                     bool allow_duplicates,
                                     size_t count, const void **contents);
 
-/* Return the current number of elements in a list.  */
+/* Returns the current number of elements in a list.  */
 extern size_t gl_list_size (gl_list_t list);
 
-/* Return the element value represented by a list node.  */
+/* Returns the element value represented by a list node.  */
 extern const void * gl_list_node_value (gl_list_t list, gl_list_node_t node);
 
-/* Replace the element value represented by a list node.  */
+/* Replaces the element value represented by a list node.  */
 /* declared in gl_xlist.h */
 extern void gl_list_node_set_value (gl_list_t list, gl_list_node_t node,
                                     const void *elt);
-/* Likewise.  Return 0 upon success, -1 upon out-of-memory.  */
+/* Likewise.  Returns 0 upon success, -1 upon out-of-memory.  */
 extern int gl_list_node_nx_set_value (gl_list_t list, gl_list_node_t node,
                                       const void *elt)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
@@ -196,25 +196,25 @@ extern int gl_list_node_nx_set_value (gl_list_t list, gl_list_node_t node,
 #endif
   ;
 
-/* Return the node immediately after the given node in the list, or NULL
+/* Returns the node immediately after the given node in the list, or NULL
    if the given node is the last (rightmost) one in the list.  */
 extern gl_list_node_t gl_list_next_node (gl_list_t list, gl_list_node_t node);
 
-/* Return the node immediately before the given node in the list, or NULL
+/* Returns the node immediately before the given node in the list, or NULL
    if the given node is the first (leftmost) one in the list.  */
 extern gl_list_node_t gl_list_previous_node (gl_list_t list, gl_list_node_t node);
 
-/* Return the element at a given position in the list.
+/* Returns the element at a given position in the list.
    POSITION must be >= 0 and < gl_list_size (list).  */
 extern const void * gl_list_get_at (gl_list_t list, size_t position);
 
-/* Replace the element at a given position in the list.
+/* Replaces the element at a given position in the list.
    POSITION must be >= 0 and < gl_list_size (list).
-   Return its node.  */
+   Returns its node.  */
 /* declared in gl_xlist.h */
 extern gl_list_node_t gl_list_set_at (gl_list_t list, size_t position,
                                       const void *elt);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_node_t gl_list_nx_set_at (gl_list_t list, size_t position,
                                          const void *elt)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
@@ -222,69 +222,69 @@ extern gl_list_node_t gl_list_nx_set_at (gl_list_t list, size_t position,
 #endif
   ;
 
-/* Search whether an element is already in the list.
-   Return its node if found, or NULL if not present in the list.  */
+/* Searches whether an element is already in the list.
+   Returns its node if found, or NULL if not present in the list.  */
 extern gl_list_node_t gl_list_search (gl_list_t list, const void *elt);
 
-/* Search whether an element is already in the list,
+/* Searches whether an element is already in the list,
    at a position >= START_INDEX.
-   Return its node if found, or NULL if not present in the list.  */
+   Returns its node if found, or NULL if not present in the list.  */
 extern gl_list_node_t gl_list_search_from (gl_list_t list, size_t start_index,
                                            const void *elt);
 
-/* Search whether an element is already in the list,
+/* Searches whether an element is already in the list,
    at a position >= START_INDEX and < END_INDEX.
-   Return its node if found, or NULL if not present in the list.  */
+   Returns its node if found, or NULL if not present in the list.  */
 extern gl_list_node_t gl_list_search_from_to (gl_list_t list,
                                               size_t start_index,
                                               size_t end_index,
                                               const void *elt);
 
-/* Search whether an element is already in the list.
-   Return its position if found, or (size_t)(-1) if not present in the list.  */
+/* Searches whether an element is already in the list.
+   Returns its position if found, or (size_t)(-1) if not present in the list.  */
 extern size_t gl_list_indexof (gl_list_t list, const void *elt);
 
-/* Search whether an element is already in the list,
+/* Searches whether an element is already in the list,
    at a position >= START_INDEX.
-   Return its position if found, or (size_t)(-1) if not present in the list.  */
+   Returns its position if found, or (size_t)(-1) if not present in the list.  */
 extern size_t gl_list_indexof_from (gl_list_t list, size_t start_index,
                                     const void *elt);
 
-/* Search whether an element is already in the list,
+/* Searches whether an element is already in the list,
    at a position >= START_INDEX and < END_INDEX.
-   Return its position if found, or (size_t)(-1) if not present in the list.  */
+   Returns its position if found, or (size_t)(-1) if not present in the list.  */
 extern size_t gl_list_indexof_from_to (gl_list_t list,
                                        size_t start_index, size_t end_index,
                                        const void *elt);
 
-/* Add an element as the first element of the list.
-   Return its node.  */
+/* Adds an element as the first element of the list.
+   Returns its node.  */
 /* declared in gl_xlist.h */
 extern gl_list_node_t gl_list_add_first (gl_list_t list, const void *elt);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_node_t gl_list_nx_add_first (gl_list_t list, const void *elt)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
   __attribute__ ((__warn_unused_result__))
 #endif
   ;
 
-/* Add an element as the last element of the list.
-   Return its node.  */
+/* Adds an element as the last element of the list.
+   Returns its node.  */
 /* declared in gl_xlist.h */
 extern gl_list_node_t gl_list_add_last (gl_list_t list, const void *elt);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_node_t gl_list_nx_add_last (gl_list_t list, const void *elt)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
   __attribute__ ((__warn_unused_result__))
 #endif
   ;
 
-/* Add an element before a given element node of the list.
-   Return its node.  */
+/* Adds an element before a given element node of the list.
+   Returns its node.  */
 /* declared in gl_xlist.h */
 extern gl_list_node_t gl_list_add_before (gl_list_t list, gl_list_node_t node,
                                           const void *elt);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_node_t gl_list_nx_add_before (gl_list_t list,
                                              gl_list_node_t node,
                                              const void *elt)
@@ -293,12 +293,12 @@ extern gl_list_node_t gl_list_nx_add_before (gl_list_t list,
 #endif
   ;
 
-/* Add an element after a given element node of the list.
-   Return its node.  */
+/* Adds an element after a given element node of the list.
+   Returns its node.  */
 /* declared in gl_xlist.h */
 extern gl_list_node_t gl_list_add_after (gl_list_t list, gl_list_node_t node,
                                          const void *elt);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_node_t gl_list_nx_add_after (gl_list_t list, gl_list_node_t node,
                                             const void *elt)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
@@ -306,12 +306,12 @@ extern gl_list_node_t gl_list_nx_add_after (gl_list_t list, gl_list_node_t node,
 #endif
   ;
 
-/* Add an element at a given position in the list.
+/* Adds an element at a given position in the list.
    POSITION must be >= 0 and <= gl_list_size (list).  */
 /* declared in gl_xlist.h */
 extern gl_list_node_t gl_list_add_at (gl_list_t list, size_t position,
                                       const void *elt);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_node_t gl_list_nx_add_at (gl_list_t list, size_t position,
                                          const void *elt)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
@@ -319,20 +319,20 @@ extern gl_list_node_t gl_list_nx_add_at (gl_list_t list, size_t position,
 #endif
   ;
 
-/* Remove an element from the list.
-   Return true.  */
+/* Removes an element from the list.
+   Returns true.  */
 extern bool gl_list_remove_node (gl_list_t list, gl_list_node_t node);
 
-/* Remove an element at a given position from the list.
+/* Removes an element at a given position from the list.
    POSITION must be >= 0 and < gl_list_size (list).
-   Return true.  */
+   Returns true.  */
 extern bool gl_list_remove_at (gl_list_t list, size_t position);
 
-/* Search and remove an element from the list.
-   Return true if it was found and removed.  */
+/* Searches and removes an element from the list.
+   Returns true if it was found and removed.  */
 extern bool gl_list_remove (gl_list_t list, const void *elt);
 
-/* Free an entire list.
+/* Frees an entire list.
    (But this call does not free the elements of the list.  It only invokes
    the DISPOSE_FN on each of the elements of the list, and only if the list
    is not a sublist.)  */
@@ -361,12 +361,12 @@ typedef struct
 
 #if 0 /* These are defined inline below.  */
 
-/* Create an iterator traversing a list.
+/* Creates an iterator traversing a list.
    The list contents must not be modified while the iterator is in use,
    except for replacing or removing the last returned element.  */
 extern gl_list_iterator_t gl_list_iterator (gl_list_t list);
 
-/* Create an iterator traversing the element with indices i,
+/* Creates an iterator traversing the element with indices i,
    start_index <= i < end_index, of a list.
    The list contents must not be modified while the iterator is in use,
    except for replacing or removing the last returned element.  */
@@ -374,13 +374,13 @@ extern gl_list_iterator_t gl_list_iterator_from_to (gl_list_t list,
                                                     size_t start_index,
                                                     size_t end_index);
 
-/* If there is a next element, store the next element in *ELTP, store its
-   node in *NODEP if NODEP is non-NULL, advance the iterator and return true.
-   Otherwise, return false.  */
+/* If there is a next element, stores the next element in *ELTP, stores its
+   node in *NODEP if NODEP is non-NULL, advances the iterator and returns true.
+   Otherwise, returns false.  */
 extern bool gl_list_iterator_next (gl_list_iterator_t *iterator,
                                    const void **eltp, gl_list_node_t *nodep);
 
-/* Free an iterator.  */
+/* Frees an iterator.  */
 extern void gl_list_iterator_free (gl_list_iterator_t *iterator);
 
 #endif /* End of inline functions.  */
@@ -396,21 +396,21 @@ typedef int (*gl_listelement_compar_fn) (const void *elt1, const void *elt2);
 
 #if 0 /* Unless otherwise specified, these are defined inline below.  */
 
-/* Search whether an element is already in the list.
+/* Searches whether an element is already in the list.
    The list is assumed to be sorted with COMPAR.
-   Return its node if found, or NULL if not present in the list.
+   Returns its node if found, or NULL if not present in the list.
    If the list contains several copies of ELT, the node of the leftmost one is
    returned.  */
 extern gl_list_node_t gl_sortedlist_search (gl_list_t list,
                                             gl_listelement_compar_fn compar,
                                             const void *elt);
 
-/* Search whether an element is already in the list.
+/* Searches whether an element is already in the list.
    The list is assumed to be sorted with COMPAR.
    Only list elements with indices >= START_INDEX and < END_INDEX are
    considered; the implementation uses these bounds to minimize the number
    of COMPAR invocations.
-   Return its node if found, or NULL if not present in the list.
+   Returns its node if found, or NULL if not present in the list.
    If the list contains several copies of ELT, the node of the leftmost one is
    returned.  */
 extern gl_list_node_t gl_sortedlist_search_from_to (gl_list_t list,
@@ -419,21 +419,21 @@ extern gl_list_node_t gl_sortedlist_search_from_to (gl_list_t list,
                                                     size_t end_index,
                                                     const void *elt);
 
-/* Search whether an element is already in the list.
+/* Searches whether an element is already in the list.
    The list is assumed to be sorted with COMPAR.
-   Return its position if found, or (size_t)(-1) if not present in the list.
+   Returns its position if found, or (size_t)(-1) if not present in the list.
    If the list contains several copies of ELT, the position of the leftmost one
    is returned.  */
 extern size_t gl_sortedlist_indexof (gl_list_t list,
                                      gl_listelement_compar_fn compar,
                                      const void *elt);
 
-/* Search whether an element is already in the list.
+/* Searches whether an element is already in the list.
    The list is assumed to be sorted with COMPAR.
    Only list elements with indices >= START_INDEX and < END_INDEX are
    considered; the implementation uses these bounds to minimize the number
    of COMPAR invocations.
-   Return its position if found, or (size_t)(-1) if not present in the list.
+   Returns its position if found, or (size_t)(-1) if not present in the list.
    If the list contains several copies of ELT, the position of the leftmost one
    is returned.  */
 extern size_t gl_sortedlist_indexof_from_to (gl_list_t list,
@@ -442,14 +442,14 @@ extern size_t gl_sortedlist_indexof_from_to (gl_list_t list,
                                              size_t end_index,
                                              const void *elt);
 
-/* Add an element at the appropriate position in the list.
+/* Adds an element at the appropriate position in the list.
    The list is assumed to be sorted with COMPAR.
-   Return its node.  */
+   Returns its node.  */
 /* declared in gl_xlist.h */
 extern gl_list_node_t gl_sortedlist_add (gl_list_t list,
                                          gl_listelement_compar_fn compar,
                                          const void *elt);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_node_t gl_sortedlist_nx_add (gl_list_t list,
                                             gl_listelement_compar_fn compar,
                                             const void *elt)
@@ -458,9 +458,9 @@ extern gl_list_node_t gl_sortedlist_nx_add (gl_list_t list,
 #endif
   ;
 
-/* Search and remove an element from the list.
+/* Searches and removes an element from the list.
    The list is assumed to be sorted with COMPAR.
-   Return true if it was found and removed.
+   Returns true if it was found and removed.
    If the list contains several copies of ELT, only the leftmost one is
    removed.  */
 extern bool gl_sortedlist_remove (gl_list_t list,
diff --git a/lib/gl_map.h b/lib/gl_map.h
index 0b33b40..8b45c83 100644
--- a/lib/gl_map.h
+++ b/lib/gl_map.h
@@ -106,7 +106,7 @@ typedef const struct gl_map_implementation * gl_map_implementation_t;
 
 #if 0 /* Unless otherwise specified, these are defined inline below.  */
 
-/* Create an empty map.
+/* Creates an empty map.
    IMPLEMENTATION is one of GL_ARRAY_MAP, GL_LINKEDHASH_MAP, GL_HASH_MAP.
    EQUALS_FN is a key comparison function or NULL.
    HASHCODE_FN is a key hash code function or NULL.
@@ -118,48 +118,48 @@ extern gl_map_t gl_map_create_empty (gl_map_implementation_t implementation,
                                      gl_mapkey_hashcode_fn hashcode_fn,
                                      gl_mapkey_dispose_fn kdispose_fn,
                                      gl_mapvalue_dispose_fn vdispose_fn);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_map_t gl_map_nx_create_empty (gl_map_implementation_t implementation,
                                         gl_mapkey_equals_fn equals_fn,
                                         gl_mapkey_hashcode_fn hashcode_fn,
                                         gl_mapkey_dispose_fn kdispose_fn,
                                         gl_mapvalue_dispose_fn vdispose_fn);
 
-/* Return the current number of pairs in a map.  */
+/* Returns the current number of pairs in a map.  */
 extern size_t gl_map_size (gl_map_t map);
 
-/* Search whether a pair with the given key is already in the map.
-   Return the value if found, or NULL if not present in the map.  */
+/* Searches whether a pair with the given key is already in the map.
+   Returns the value if found, or NULL if not present in the map.  */
 extern const void * gl_map_get (gl_map_t map, const void *key);
 
-/* Search whether a pair with the given key is already in the map.
-   Return true and set *VALUEP to the value if found.
-   Return false if not present in the map.  */
+/* Searches whether a pair with the given key is already in the map.
+   Returns true and sets *VALUEP to the value if found.
+   Returns false if not present in the map.  */
 extern bool gl_map_search (gl_map_t map, const void *key, const void **valuep);
 
-/* Add a pair to a map.
-   Return true if a pair with the given key was not already in the map and so
+/* Adds a pair to a map.
+   Returns true if a pair with the given key was not already in the map and so
    this pair was added.
-   Return false if a pair with the given key was already in the map and only
+   Returns false if a pair with the given key was already in the map and only
    its value was replaced.  */
 /* declared in gl_xmap.h */
 extern bool gl_map_put (gl_map_t map, const void *key, const void *value);
-/* Likewise.  Return -1 upon out-of-memory.  */
+/* Likewise.  Returns -1 upon out-of-memory.  */
 extern int gl_map_nx_put (gl_map_t map, const void *key, const void *value)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
   __attribute__ ((__warn_unused_result__))
 #endif
   ;
 
-/* Add a pair to a map and retrieve the previous value.
-   Return true if a pair with the given key was not already in the map and so
+/* Adds a pair to a map and retrieves the previous value.
+   Returns true if a pair with the given key was not already in the map and so
    this pair was added.
-   Return false and set *OLDVALUEP to the previous value, if a pair with the
+   Returns false and sets *OLDVALUEP to the previous value, if a pair with the
    given key was already in the map and only its value was replaced.  */
 /* declared in gl_xmap.h */
 extern bool gl_map_getput (gl_map_t map, const void *key, const void *value,
                            const void **oldvaluep);
-/* Likewise.  Return -1 upon out-of-memory.  */
+/* Likewise.  Returns -1 upon out-of-memory.  */
 extern int gl_map_nx_getput (gl_map_t map, const void *key, const void *value,
                              const void **oldvaluep)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
@@ -167,19 +167,19 @@ extern int gl_map_nx_getput (gl_map_t map, const void *key, const void *value,
 #endif
   ;
 
-/* Remove a pair from a map.
-   Return true if the key was found and its pair removed.
-   Return false otherwise.  */
+/* Removes a pair from a map.
+   Returns true if the key was found and its pair removed.
+   Returns false otherwise.  */
 extern bool gl_map_remove (gl_map_t map, const void *key);
 
-/* Remove a pair from a map and retrieve the previous value.
-   Return true and set *OLDVALUEP to the previous value, if the key was found
+/* Removes a pair from a map and retrieve the previous value.
+   Returns true and sets *OLDVALUEP to the previous value, if the key was found
    and its pair removed.
-   Return false otherwise.  */
+   Returns false otherwise.  */
 extern bool gl_map_getremove (gl_map_t map, const void *key,
                               const void **oldvaluep);
 
-/* Free an entire map.
+/* Frees an entire map.
    (But this call does not free the keys and values of the pairs in the map.
    It only invokes the KDISPOSE_FN on each key and the VDISPOSE_FN on each value
    of the pairs in the map.)  */
@@ -211,18 +211,18 @@ typedef struct
 
 #if 0 /* These are defined inline below.  */
 
-/* Create an iterator traversing a map.
+/* Creates an iterator traversing a map.
    The map's contents must not be modified while the iterator is in use,
    except for modifying the value of the last returned key or removing the
    last returned pair.  */
 extern gl_map_iterator_t gl_map_iterator (gl_map_t map);
 
-/* If there is a next pair, store the next pair in *KEYP and *VALUEP, advance
-   the iterator, and return true.  Otherwise, return false.  */
+/* If there is a next pair, stores the next pair in *KEYP and *VALUEP, advances
+   the iterator, and returns true.  Otherwise, returns false.  */
 extern bool gl_map_iterator_next (gl_map_iterator_t *iterator,
                                   const void **keyp, const void **valuep);
 
-/* Free an iterator.  */
+/* Frees an iterator.  */
 extern void gl_map_iterator_free (gl_map_iterator_t *iterator);
 
 #endif /* End of inline functions.  */
diff --git a/lib/gl_omap.h b/lib/gl_omap.h
index cbd4414..afb4411 100644
--- a/lib/gl_omap.h
+++ b/lib/gl_omap.h
@@ -95,7 +95,7 @@ typedef void (*gl_mapvalue_dispose_fn) (const void *value);
 #endif
 
 /* Type of function used to compare a key with a threshold.
-   Return true if the key is greater or equal than the threshold.  */
+   Returns true if the key is greater or equal than the threshold.  */
 typedef bool (*gl_mapkey_threshold_fn) (const void *key, const void *threshold);
 
 struct gl_omap_impl;
@@ -108,7 +108,7 @@ typedef const struct gl_omap_implementation * gl_omap_implementation_t;
 
 #if 0 /* Unless otherwise specified, these are defined inline below.  */
 
-/* Create an empty map.
+/* Creates an empty map.
    IMPLEMENTATION is one of GL_ARRAY_OMAP, GL_AVLTREE_OMAP, GL_RBTREE_OMAP.
    COMPAR_FN is a key comparison function or NULL.
    KDISPOSE_FN is a key disposal function or NULL.
@@ -118,58 +118,58 @@ extern gl_omap_t gl_omap_create_empty (gl_omap_implementation_t implementation,
                                        gl_mapkey_compar_fn compar_fn,
                                        gl_mapkey_dispose_fn kdispose_fn,
                                        gl_mapvalue_dispose_fn vdispose_fn);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_omap_t gl_omap_nx_create_empty (gl_omap_implementation_t implementation,
                                           gl_mapkey_compar_fn compar_fn,
                                           gl_mapkey_dispose_fn kdispose_fn,
                                           gl_mapvalue_dispose_fn vdispose_fn);
 
-/* Return the current number of pairs in an ordered map.  */
+/* Returns the current number of pairs in an ordered map.  */
 extern size_t gl_omap_size (gl_omap_t map);
 
-/* Search whether a pair with the given key is already in the ordered map.
-   Return the value if found, or NULL if not present in the map.  */
+/* Searches whether a pair with the given key is already in the ordered map.
+   Returns the value if found, or NULL if not present in the map.  */
 extern const void * gl_omap_get (gl_omap_t map, const void *key);
 
-/* Search whether a pair with the given key is already in the ordered map.
-   Return true and set *VALUEP to the value if found.
-   Return false if not present in the map.  */
+/* Searches whether a pair with the given key is already in the ordered map.
+   Returns true and sets *VALUEP to the value if found.
+   Returns false if not present in the map.  */
 extern bool gl_omap_search (gl_omap_t map, const void *key,
                             const void **valuep);
 
-/* Search the pair with the least key in the ordered map that compares
+/* Searches the pair with the least key in the ordered map that compares
    greater or equal to the given THRESHOLD.  The representation of the
    THRESHOLD is defined by the THRESHOLD_FN.
-   Return true and store the found pair in *KEYP and *VALUEP if found.
-   Otherwise return false.  */
+   Returns true and stores the found pair in *KEYP and *VALUEP if found.
+   Otherwise returns false.  */
 extern bool gl_omap_search_atleast (gl_omap_t map,
                                     gl_mapkey_threshold_fn threshold_fn,
                                     const void *threshold,
                                     const void **keyp, const void **valuep);
 
-/* Add a pair to an ordered map.
-   Return true if a pair with the given key was not already in the map and so
+/* Adds a pair to an ordered map.
+   Returns true if a pair with the given key was not already in the map and so
    this pair was added.
-   Return false if a pair with the given key was already in the map and only
+   Returns false if a pair with the given key was already in the map and only
    its value was replaced.  */
 /* declared in gl_xomap.h */
 extern bool gl_omap_put (gl_omap_t map, const void *key, const void *value);
-/* Likewise.  Return -1 upon out-of-memory.  */
+/* Likewise.  Returns -1 upon out-of-memory.  */
 extern int gl_omap_nx_put (gl_omap_t map, const void *key, const void *value)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
   __attribute__ ((__warn_unused_result__))
 #endif
   ;
 
-/* Add a pair to an ordered map and retrieve the previous value.
-   Return true if a pair with the given key was not already in the map and so
+/* Adds a pair to an ordered map and retrieve the previous value.
+   Returns true if a pair with the given key was not already in the map and so
    this pair was added.
-   Return false and set *OLDVALUEP to the previous value, if a pair with the
+   Returns false and sets *OLDVALUEP to the previous value, if a pair with the
    given key was already in the map and only its value was replaced.  */
 /* declared in gl_xomap.h */
 extern bool gl_omap_getput (gl_omap_t map, const void *key, const void *value,
                             const void **oldvaluep);
-/* Likewise.  Return -1 upon out-of-memory.  */
+/* Likewise.  Returns -1 upon out-of-memory.  */
 extern int gl_omap_nx_getput (gl_omap_t map, const void *key, const void *value,
                               const void **oldvaluep)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
@@ -177,19 +177,19 @@ extern int gl_omap_nx_getput (gl_omap_t map, const void *key, const void *value,
 #endif
   ;
 
-/* Remove a pair from an ordered map.
-   Return true if the key was found and its pair removed.
-   Return false otherwise.  */
+/* Removes a pair from an ordered map.
+   Returns true if the key was found and its pair removed.
+   Returns false otherwise.  */
 extern bool gl_omap_remove (gl_omap_t map, const void *key);
 
-/* Remove a pair from an ordered map and retrieve the previous value.
-   Return true and set *OLDVALUEP to the previous value, if the key was found
+/* Removes a pair from an ordered map and retrieve the previous value.
+   Returns true and sets *OLDVALUEP to the previous value, if the key was found
    and its pair removed.
-   Return false otherwise.  */
+   Returns false otherwise.  */
 extern bool gl_omap_getremove (gl_omap_t map, const void *key,
                                const void **oldvaluep);
 
-/* Free an entire ordered map.
+/* Frees an entire ordered map.
    (But this call does not free the keys and values of the pairs in the map.
    It only invokes the KDISPOSE_FN on each key and the VDISPOSE_FN on each value
    of the pairs in the map.)  */
@@ -218,18 +218,18 @@ typedef struct
 
 #if 0 /* These are defined inline below.  */
 
-/* Create an iterator traversing an ordered map.
+/* Creates an iterator traversing an ordered map.
    The map's contents must not be modified while the iterator is in use,
    except for modifying the value of the last returned key or removing the
    last returned pair.  */
 extern gl_omap_iterator_t gl_omap_iterator (gl_omap_t map);
 
-/* If there is a next pair, store the next pair in *KEYP and *VALUEP, advance
-   the iterator, and return true.  Otherwise, return false.  */
+/* If there is a next pair, stores the next pair in *KEYP and *VALUEP, advances
+   the iterator, and returns true.  Otherwise, returns false.  */
 extern bool gl_omap_iterator_next (gl_omap_iterator_t *iterator,
                                    const void **keyp, const void **valuep);
 
-/* Free an iterator.  */
+/* Frees an iterator.  */
 extern void gl_omap_iterator_free (gl_omap_iterator_t *iterator);
 
 #endif /* End of inline functions.  */
diff --git a/lib/gl_oset.h b/lib/gl_oset.h
index 216139c..d6fb408 100644
--- a/lib/gl_oset.h
+++ b/lib/gl_oset.h
@@ -85,7 +85,7 @@ typedef void (*gl_setelement_dispose_fn) (const void *elt);
 #endif
 
 /* Type of function used to compare an element with a threshold.
-   Return true if the element is greater or equal than the threshold.  */
+   Returns true if the element is greater or equal than the threshold.  */
 typedef bool (*gl_setelement_threshold_fn) (const void *elt, const void *threshold);
 
 struct gl_oset_impl;
@@ -98,7 +98,7 @@ typedef const struct gl_oset_implementation * gl_oset_implementation_t;
 
 #if 0 /* Unless otherwise specified, these are defined inline below.  */
 
-/* Create an empty set.
+/* Creates an empty set.
    IMPLEMENTATION is one of GL_ARRAY_OSET, GL_AVLTREE_OSET, GL_RBTREE_OSET.
    COMPAR_FN is an element comparison function or NULL.
    DISPOSE_FN is an element disposal function or NULL.  */
@@ -106,44 +106,44 @@ typedef const struct gl_oset_implementation * gl_oset_implementation_t;
 extern gl_oset_t gl_oset_create_empty (gl_oset_implementation_t implementation,
                                        gl_setelement_compar_fn compar_fn,
                                        gl_setelement_dispose_fn dispose_fn);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_oset_t gl_oset_nx_create_empty (gl_oset_implementation_t implementation,
                                           gl_setelement_compar_fn compar_fn,
                                           gl_setelement_dispose_fn dispose_fn);
 
-/* Return the current number of elements in an ordered set.  */
+/* Returns the current number of elements in an ordered set.  */
 extern size_t gl_oset_size (gl_oset_t set);
 
-/* Search whether an element is already in the ordered set.
-   Return true if found, or false if not present in the set.  */
+/* Searches whether an element is already in the ordered set.
+   Returns true if found, or false if not present in the set.  */
 extern bool gl_oset_search (gl_oset_t set, const void *elt);
 
-/* Search the least element in the ordered set that compares greater or equal
+/* Searches the least element in the ordered set that compares greater or equal
    to the given THRESHOLD.  The representation of the THRESHOLD is defined
    by the THRESHOLD_FN.
-   Return true and store the found element in *ELTP if found, otherwise return
+   Returns true and stores the found element in *ELTP if found, otherwise returns
    false.  */
 extern bool gl_oset_search_atleast (gl_oset_t set,
                                     gl_setelement_threshold_fn threshold_fn,
                                     const void *threshold,
                                     const void **eltp);
 
-/* Add an element to an ordered set.
-   Return true if it was not already in the set and added, false otherwise.  */
+/* Adds an element to an ordered set.
+   Returns true if it was not already in the set and added, false otherwise.  */
 /* declared in gl_xoset.h */
 extern bool gl_oset_add (gl_oset_t set, const void *elt);
-/* Likewise.  Return -1 upon out-of-memory.  */
+/* Likewise.  Returns -1 upon out-of-memory.  */
 extern int gl_oset_nx_add (gl_oset_t set, const void *elt)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
   __attribute__ ((__warn_unused_result__))
 #endif
   ;
 
-/* Remove an element from an ordered set.
-   Return true if it was found and removed.  */
+/* Removes an element from an ordered set.
+   Returns true if it was found and removed.  */
 extern bool gl_oset_remove (gl_oset_t set, const void *elt);
 
-/* Free an entire ordered set.
+/* Frees an entire ordered set.
    (But this call does not free the elements of the set.  It only invokes
    the DISPOSE_FN on each of the elements of the set.)  */
 extern void gl_oset_free (gl_oset_t set);
@@ -171,17 +171,17 @@ typedef struct
 
 #if 0 /* These are defined inline below.  */
 
-/* Create an iterator traversing an ordered set.
+/* Creates an iterator traversing an ordered set.
    The set's contents must not be modified while the iterator is in use,
    except for removing the last returned element.  */
 extern gl_oset_iterator_t gl_oset_iterator (gl_oset_t set);
 
-/* If there is a next element, store the next element in *ELTP, advance the
-   iterator and return true.  Otherwise, return false.  */
+/* If there is a next element, stores the next element in *ELTP, advances the
+   iterator and returns true.  Otherwise, returns false.  */
 extern bool gl_oset_iterator_next (gl_oset_iterator_t *iterator,
                                    const void **eltp);
 
-/* Free an iterator.  */
+/* Frees an iterator.  */
 extern void gl_oset_iterator_free (gl_oset_iterator_t *iterator);
 
 #endif /* End of inline functions.  */
diff --git a/lib/gl_rbtree_ordered.h b/lib/gl_rbtree_ordered.h
index b41c6d2..f7a5988 100644
--- a/lib/gl_rbtree_ordered.h
+++ b/lib/gl_rbtree_ordered.h
@@ -63,7 +63,7 @@ struct CONTAINER_IMPL
    this would exceed the address space of the machine.  */
 #define MAXHEIGHT 116
 
-/* Rotate left a subtree.
+/* Rotates left a subtree.
 
                          B                         D
                        /   \                     /   \
@@ -71,7 +71,7 @@ struct CONTAINER_IMPL
                             / \               / \
                            C   E             A   C
 
-   Change the tree structure, update the branch sizes.
+   Changes the tree structure, updates the branch sizes.
    The caller must update the colors and register D as child of its parent.  */
 static NODE_T
 rotate_left (NODE_T b_node, NODE_T d_node)
@@ -89,7 +89,7 @@ rotate_left (NODE_T b_node, NODE_T d_node)
   return d_node;
 }
 
-/* Rotate right a subtree.
+/* Rotates right a subtree.
 
                            D                     B
                          /   \                 /   \
@@ -97,7 +97,7 @@ rotate_left (NODE_T b_node, NODE_T d_node)
                       / \                           / \
                      A   C                         C   E
 
-   Change the tree structure, update the branch sizes.
+   Changes the tree structure, updates the branch sizes.
    The caller must update the colors and register B as child of its parent.  */
 static NODE_T
 rotate_right (NODE_T b_node, NODE_T d_node)
@@ -115,7 +115,7 @@ rotate_right (NODE_T b_node, NODE_T d_node)
   return b_node;
 }
 
-/* Ensure the tree is balanced, after an insertion operation.
+/* Ensures the tree is balanced, after an insertion operation.
    Also assigns node->color.
    parent is the given node's parent, known to be non-NULL.  */
 static void
@@ -239,7 +239,7 @@ rebalance_after_add (CONTAINER_T container, NODE_T node, NODE_T parent)
     }
 }
 
-/* Ensure the tree is balanced, after a deletion operation.
+/* Ensures the tree is balanced, after a deletion operation.
    CHILD was a grandchild of PARENT and is now its child.  Between them,
    a black node was removed.  CHILD is also black, or NULL.
    (CHILD can also be NULL.  But PARENT is non-NULL.)  */
diff --git a/lib/gl_set.h b/lib/gl_set.h
index dfad8a8..0c1f9a3 100644
--- a/lib/gl_set.h
+++ b/lib/gl_set.h
@@ -97,7 +97,7 @@ typedef const struct gl_set_implementation * gl_set_implementation_t;
 
 #if 0 /* Unless otherwise specified, these are defined inline below.  */
 
-/* Create an empty set.
+/* Creates an empty set.
    IMPLEMENTATION is one of GL_ARRAY_SET, GL_LINKEDHASH_SET, GL_HASH_SET.
    EQUALS_FN is an element comparison function or NULL.
    HASHCODE_FN is an element hash code function or NULL.
@@ -107,35 +107,35 @@ extern gl_set_t gl_set_create_empty (gl_set_implementation_t implementation,
                                      gl_setelement_equals_fn equals_fn,
                                      gl_setelement_hashcode_fn hashcode_fn,
                                      gl_setelement_dispose_fn dispose_fn);
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_set_t gl_set_nx_create_empty (gl_set_implementation_t implementation,
                                         gl_setelement_equals_fn equals_fn,
                                         gl_setelement_hashcode_fn hashcode_fn,
                                         gl_setelement_dispose_fn dispose_fn);
 
-/* Return the current number of elements in a set.  */
+/* Returns the current number of elements in a set.  */
 extern size_t gl_set_size (gl_set_t set);
 
-/* Search whether an element is already in the set.
-   Return true if found, or false if not present in the set.  */
+/* Searches whether an element is already in the set.
+   Returns true if found, or false if not present in the set.  */
 extern bool gl_set_search (gl_set_t set, const void *elt);
 
-/* Add an element to a set.
-   Return true if it was not already in the set and added, false otherwise.  */
+/* Adds an element to a set.
+   Returns true if it was not already in the set and added, false otherwise.  */
 /* declared in gl_xset.h */
 extern bool gl_set_add (gl_set_t set, const void *elt);
-/* Likewise.  Return -1 upon out-of-memory.  */
+/* Likewise.  Returns -1 upon out-of-memory.  */
 extern int gl_set_nx_add (gl_set_t set, const void *elt)
 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
   __attribute__ ((__warn_unused_result__))
 #endif
   ;
 
-/* Remove an element from a set.
-   Return true if it was found and removed.  */
+/* Removes an element from a set.
+   Returns true if it was found and removed.  */
 extern bool gl_set_remove (gl_set_t set, const void *elt);
 
-/* Free an entire set.
+/* Frees an entire set.
    (But this call does not free the elements of the set.  It only invokes
    the DISPOSE_FN on each of the elements of the set.)  */
 extern void gl_set_free (gl_set_t set);
@@ -166,17 +166,17 @@ typedef struct
 
 #if 0 /* These are defined inline below.  */
 
-/* Create an iterator traversing a set.
+/* Creates an iterator traversing a set.
    The set's contents must not be modified while the iterator is in use,
    except for removing the last returned element.  */
 extern gl_set_iterator_t gl_set_iterator (gl_set_t set);
 
-/* If there is a next element, store the next element in *ELTP, advance the
-   iterator and return true.  Otherwise, return false.  */
+/* If there is a next element, stores the next element in *ELTP, advances the
+   iterator and returns true.  Otherwise, returns false.  */
 extern bool gl_set_iterator_next (gl_set_iterator_t *iterator,
                                   const void **eltp);
 
-/* Free an iterator.  */
+/* Frees an iterator.  */
 extern void gl_set_iterator_free (gl_set_iterator_t *iterator);
 
 #endif /* End of inline functions.  */
diff --git a/lib/gl_sublist.h b/lib/gl_sublist.h
index 36fc746..5ad574a 100644
--- a/lib/gl_sublist.h
+++ b/lib/gl_sublist.h
@@ -25,7 +25,7 @@ extern "C" {
 #endif
 
 
-/* Create a sublist of a given list.
+/* Creates a sublist of a given list.
    This is the list of elements with indices i, start_index <= i < end_index.
    The sublist is backed by the given list, which means:
      - Modifications to the sublist affect the whole list.
@@ -37,7 +37,7 @@ extern "C" {
 extern gl_list_t gl_sublist_create (gl_list_t whole_list,
                                     size_t start_index, size_t end_index);
 #endif
-/* Likewise.  Return NULL upon out-of-memory.  */
+/* Likewise.  Returns NULL upon out-of-memory.  */
 extern gl_list_t gl_sublist_nx_create (gl_list_t whole_list,
                                        size_t start_index, size_t end_index);
 

Re: list, set, oset, map, omap: avoid imperative voice in documentation

[Jim Meyering]

On Sun, Feb 2, 2020 at 4:17 AM Bruno Haible <bruno@clisp.org> wrote:
> Each time I read the function specifications in gl_list.h, the use of
> imperative voice ("Return true if ...") feels wrong. "Returns true if ..." is
> the correct grammar.
>
> Why? Because imperative form is used to instruct someone. In the context
> of the documentation of a function, there are two "who"s involved:
>   - (A) the programmer who implemented the function,
>   - (B) the programmer who wants to invoke the function.
> Thus, the only valid use of imperative form in this context is an
> instruction for (B), for example: "Don't pass a negative value as argument."
>
> Things are different inside the function definition: Here, (B) is not
> supposed to look. The two "who"s here are:
>   - (A) the programmer who implemented the function,
>   - (C) the machine which executes the code.
> Here, an imperative voice from (A) to (C) is reasonable.
>
> The Python people get this wrong [1]. Probably because they put the
> specification of a function at the beginning of the function definition,
> and thus blur the distinction between documentation and function definition.
>
> [1] https://www.python.org/dev/peps/pep-0257/
>
>
> 2020-02-02  Bruno Haible  <bruno@clisp.org>
>
>         list, set, oset, map, omap: Avoid imperative voice in documentation.
>         * lib/gl_list.h: Use descriptive sentences instead of imperative voice
>         in the specification of functions.
>         * lib/gl_set.h: Likewise.
>         * lib/gl_oset.h: Likewise.
>         * lib/gl_map.h: Likewise.
>         * lib/gl_omap.h: Likewise.
>         * lib/gl_*.h: Likewise.

Hi Bruno,

I have made so many s/Returns/Return/ changes that I have a visceral
negative reaction to this change.

Perhaps it's because I have been writing deliberately imperative and
active-voice comments for so long that I find no ambiguity there. I
find those comments to be grammatically correct and easier to read
than the other forms. Also more concise, even if often only by one
letter. If I must speak of constraints on what the caller does, I'd
say something like "Freeing FOO is the responsibility of the caller."

IMHO, it is obvious from the context that the comment is not telling
"(B) the programmer who wants to invoke the function" to return.

Perhaps as in those python guidelines, I do not think it is worthwhile
to use different writing styles/voices between header and non-header
files.

Thank you for your indefatigable work on gnulib!

Jim

Re: list, set, oset, map, omap: avoid imperative voice in documentation

[Bruno Haible]

Hi Jim,

> Perhaps it's because I have been writing deliberately imperative and
> active-voice comments for so long that I find no ambiguity there.

Yes, 13 years ago, apparently I used this style as well. Nowadays I'm
used to the descriptive style, because it is more established. [1]

> I have made so many s/Returns/Return/ changes that I have a visceral
> negative reaction to this change.

Even in GNU, and specifically in Emacs Lisp, it's inconsistent: While
the Emacs "Tips for Documentation Strings" [2] asks for imperative style,
large parts of the Emacs Reference Documentation [3] have switched to
"This function <descriptive style>". For example
"This function returns t ..." [4].

> Perhaps as in those python guidelines, I do not think it is worthwhile
> to use different writing styles/voices between header and non-header
> files.

Yes, function descriptions in non-header files (for 'static' functions)
should be treated like function descriptions in header files, IMO.

The real difference is: Am I talking to a user of the function? Or am
I explaining the implementation details of the function?

Bruno

[1] http://lua-users.org/lists/lua-l/2012-03/msg00785.html
[2] https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
[3] https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html
[4] https://www.gnu.org/software/emacs/manual/html_node/elisp/Symbols.html

Re: list, set, oset, map, omap: avoid imperative voice in documentation

[Paul Eggert]

I'm with Jim. The imperative style is shorter, matches the style of the 
imperative programming language we're using, and is more grammatical in 
the sense that "Free an iterator." is an English sentence whereas "Frees 
an iterator." is not.

Plus, it's odd to use one style before a "{" and a different style after.

> The real difference is: Am I talking to a user of the function? Or am
> I explaining the implementation details of the function?

When talking to a function's user, it's fine for the comment to stand 
for a call to the function. For example:

/* Clear the error indicator for STREAM.  */
void clearerr (FILE *__stream);

This comment is saying "'Clear the error indicator for STREAM' = 
'clearerr (STREAM)'." In contrast, if we change the comment's "Clear" to 
"Clears" then the comment is saying something like "'Clears the error 
indicator for STREAM' is something that 'clearerr (STREAM)' does." which 
is indirect and awkward, or perhaps "'clearerr (STREAM)' clears the 
error indicator for STREAM." which is in reverse order of what the text 
says - and either way the "Clears" of the comment disagrees with the 
"clear" of the function name.

Re: list, set, oset, map, omap: avoid imperative voice in documentation

[Bruno Haible]

Paul Eggert wrote:
> Plus, it's odd to use one style before a "{" and a different style after.

I think it's useful to make this emphasis - in order to write a function
specification that can be understood without reading the function body.

When I write code, I'm of course a bit annoyed to make the difference
between the specification (in the .h file) and the implementation (in the
.c file). But this annoyance is rewarded with a 10 times higher value:
the ability to read the specification without looking into the implementation
(which is often 3 to 20 times larger than the specification).

> perhaps "'clearerr (STREAM)' clears the 
> error indicator for STREAM." which is in reverse order of what the text 
> says

That's only because we are writing the specification before the declaration,
and directly looking at the .h file. If you were reading Doxygen generated
HTML [1], it would present the declaration first and the specification
immediately following it.

> the "Clears" of the comment disagrees with the "clear" of the function name.

Yes, function names use the imperative, like C does: we write
   goto label;           NOT       goesto label;
and
   return x;             NOT       returns x;
- because inside the function's body the imperative aspects are predominant.

Bruno

[1] http://xerces.apache.org/xerces-c/apiDocs-3/classBase64.html