From 5307371bf319d730adf0a7f2fa91eacd949f1fdd Mon Sep 17 00:00:00 2001
From: riastradh <riastradh@NetBSD.org>
Date: Fri, 28 Aug 2020 07:03:41 +0000
Subject: [PATCH] thmap(9): Minor readability and style tweaks.

- Fix typo: hmap -> thmap

- Reduce excessive indentation.

- Specify largest entry width for flag name table.

- Include parameter names in function descriptions for easier
  reference.
---
 share/man/man9/thmap.9 | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/share/man/man9/thmap.9 b/share/man/man9/thmap.9
index ef1468ad1051..37594e28e0a9 100644
--- a/share/man/man9/thmap.9
+++ b/share/man/man9/thmap.9
@@ -1,4 +1,4 @@
-.\" $NetBSD: thmap.9,v 1.2 2019/08/28 22:11:25 wiz Exp $
+.\" $NetBSD: thmap.9,v 1.3 2020/08/28 07:03:41 riastradh Exp $
 .\"
 .\" Copyright (c) 2018 Mindaugas Rasiukevicius <rmind at noxt eu>
 .\" All rights reserved.
@@ -36,17 +36,17 @@
 .Ft thmap_t *
 .Fn thmap_create "uintptr_t baseptr" "const thmap_ops_t *ops" "unsigned flags"
 .Ft void
-.Fn thmap_destroy "thmap_t *hmap"
+.Fn thmap_destroy "thmap_t *thmap"
 .Ft void *
-.Fn thmap_get "thmap_t *hmap" "const void *key" "size_t len"
+.Fn thmap_get "thmap_t *thmap" "const void *key" "size_t len"
 .Ft void *
-.Fn thmap_put "thmap_t *hmap" "const void *key" "size_t len" "void *val"
+.Fn thmap_put "thmap_t *thmap" "const void *key" "size_t len" "void *val"
 .Ft void *
-.Fn thmap_del "thmap_t *hmap" "const void *key" "size_t len"
+.Fn thmap_del "thmap_t *thmap" "const void *key" "size_t len"
 .Ft void *
-.Fn thmap_stage_gc "thmap_t *hmap"
+.Fn thmap_stage_gc "thmap_t *thmap"
 .Ft void
-.Fn thmap_gc "thmap_t *hmap" "void *ref"
+.Fn thmap_gc "thmap_t *thmap" "void *ref"
 .Ft void
 .Fn thmap_setroot "thmap_t *thmap" "uintptr_t root_offset"
 .Ft uintptr_t
@@ -72,8 +72,8 @@ Delete operations (the key/data destruction) must be synchronized with
 the readers using some reclamation mechanism.
 .\" -----
 .Sh FUNCTIONS
-.Bl -tag -width thmap_create
-.It Fn thmap_create
+.Bl -tag -width abcd
+.It Fn thmap_create baseptr ops flags
 Construct a new trie-hash map.
 The optional
 .Fa ops
@@ -99,7 +99,7 @@ should be set to zero.
 Currently, the supported
 .Fa flags
 are:
-.Bl -tag -width THMAP_NOCOPY
+.Bl -tag -width THMAP_SETROOT
 .It Dv THMAP_NOCOPY
 The keys on insert will not be copied and the given pointers to them will
 be expected to be valid and the values constant until the key is deleted;
@@ -112,10 +112,10 @@ by default, the map is initialized and the root node is set on
 .Fn thmap_create .
 .El
 .\" ---
-.It Fn thmap_destroy
+.It Fn thmap_destroy thmap
 Destroy the map, freeing the memory it uses.
 .\" ---
-.It Fn thmap_get
+.It Fn thmap_get thmap key len
 Lookup the key (of a given length) and return the value associated with it.
 Return
 .Dv NULL
@@ -123,7 +123,7 @@ if the key is not found (see the
 .Sx CAVEATS
 section).
 .\" ---
-.It Fn thmap_put
+.It Fn thmap_put thmap key len val
 Insert the key with an arbitrary value.
 If the key is already present, return the already existing associated value
 without changing it.
@@ -132,7 +132,7 @@ Just compare the result against
 .Fa val
 to test whether the insert was successful.
 .\" ---
-.It Fn thmap_del
+.It Fn thmap_del thmap key len
 Remove the given key.
 If the key was present, return the associated value;
 otherwise return
@@ -146,7 +146,7 @@ and
 .Fn thmap_gc
 routines.
 .\" ---
-.It Fn thmap_stage_gc
+.It Fn thmap_stage_gc thmap
 Stage the currently pending entries (the memory not yet released after
 the deletion) for reclamation (G/C).
 This operation should be called
@@ -158,7 +158,7 @@ Returns a reference which must be passed to
 Not calling the G/C function for the returned reference would result in
 a memory leak.
 .\" ---
-.It Fn thmap_gc
+.It Fn thmap_gc thmap ref
 Reclaim (G/C) the staged entries i.e. release any memory associated
 with the deleted keys.
 The reference must be the value returned by the call to
@@ -175,14 +175,14 @@ If the map is created using the
 .Fa THMAP_SETROOT
 flag, then the following functions are applicable:
 .\" ---
-.Bl -tag -width thmap_setroot
-.It Fn thmap_setroot
+.Bl -tag -width abcd
+.It Fn thmap_setroot thmap root_offset
 Set the root node.
 The address must be relative to the base address, as if allocated by the
 .Fn thmap_ops_t::alloc
 routine.
 Return 0 on success and \-1 on failure (if already set).
-.It Fn thmap_getroot
+.It Fn thmap_getroot thmap
 Get the root node address.
 The returned address will be relative to the base address.
 .El