[src/trunk]: src/share/man/man9 thmap(9): Minor readability and style tweaks.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/8f0d7b275e44
branches:  trunk
changeset: 937867:8f0d7b275e44
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Fri Aug 28 07:03:41 2020 +0000

description:
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.

diffstat:

 share/man/man9/thmap.9 |  38 +++++++++++++++++++-------------------
 1 files changed, 19 insertions(+), 19 deletions(-)

diffs (120 lines):

diff -r 7866920d2748 -r 8f0d7b275e44 share/man/man9/thmap.9
--- a/share/man/man9/thmap.9    Fri Aug 28 07:03:08 2020 +0000
+++ b/share/man/man9/thmap.9    Fri Aug 28 07:03:41 2020 +0000
@@ -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 @@
 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 @@
 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 @@
 .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 @@
 .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 @@
 .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 @@
 .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 @@
 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 @@
 .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