Stats API converted to mdbook.

A number of small errors were fixed, and we tried to restructure
this to be a bit more usable to readers.

21 files changed, 268 insertions, 998 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 4183c316..0df0990d 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -229,29 +229,29 @@ that route messages from one socket to another.
 |xref:nng_device.3.adoc[nng_device()]|message forwarding device
 |===
 
-=== Statistics
+// === Statistics
 
-The following functions provide access to statistics which can be used
-to observe program behaviors and as an aid in troubleshooting.
+// The following functions provide access to statistics which can be used
+// to observe program behaviors and as an aid in troubleshooting.
 
-|===
-|xref:nng_stat_bool.3.adoc[nng_stat_bool()]|get statistic Boolean value
-|xref:nng_stat_child.3.adoc[nng_stat_child()]|get child statistic
-|xref:nng_stat_desc.3.adoc[nng_stat_name()]|get statistic description
-|xref:nng_stat_find.3.adoc[nng_stat_find()]|find statistic by name
-|xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer()]|find dialer statistics
-|xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener()]|find listener statistics
-|xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket()]|find socket statistics
-|xref:nng_stat_name.3.adoc[nng_stat_name()]|get statistic name
-|xref:nng_stat_next.3.adoc[nng_stat_next()]|get next statistic
-|xref:nng_stat_string.3.adoc[nng_stat_string()]|get statistic string value
-|xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp()]|get statistic timestamp
-|xref:nng_stat_type.3.adoc[nng_stat_type()]|get statistic type
-|xref:nng_stat_unit.3.adoc[nng_stat_unit()]|get statistic unit
-|xref:nng_stat_value.3.adoc[nng_stat_value()]|get statistic numeric value
-|xref:nng_stats_free.3.adoc[nng_stats_free()]|free statistics
-|xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics
-|===
+// |===
+// |xref:nng_stat_bool.3.adoc[nng_stat_bool()]|get statistic Boolean value
+// |xref:nng_stat_child.3.adoc[nng_stat_child()]|get child statistic
+// |xref:nng_stat_desc.3.adoc[nng_stat_name()]|get statistic description
+// |xref:nng_stat_find.3.adoc[nng_stat_find()]|find statistic by name
+// |xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer()]|find dialer statistics
+// |xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener()]|find listener statistics
+// |xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket()]|find socket statistics
+// |xref:nng_stat_name.3.adoc[nng_stat_name()]|get statistic name
+// |xref:nng_stat_next.3.adoc[nng_stat_next()]|get next statistic
+// |xref:nng_stat_string.3.adoc[nng_stat_string()]|get statistic string value
+// |xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp()]|get statistic timestamp
+// |xref:nng_stat_type.3.adoc[nng_stat_type()]|get statistic type
+// |xref:nng_stat_unit.3.adoc[nng_stat_unit()]|get statistic unit
+// |xref:nng_stat_value.3.adoc[nng_stat_value()]|get statistic numeric value
+// |xref:nng_stats_free.3.adoc[nng_stats_free()]|free statistics
+// |xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics
+// |===
 
 // === URL Object
 
@@ -275,9 +275,9 @@ to observe program behaviors and as an aid in troubleshooting.
 // |xref:nng_log_logger.3.adoc[nng_log_set_logger()]|set logging handler
 // |===
 
-=== Supplemental API
+// === Supplemental API
 
-NOTE: All these functions have been moved to new mdbook docs.
+// NOTE: All these functions have been moved to new mdbook docs.
 
 // These supplemental functions are not intrinsic to building
 // network applications with _NNG_, but they are made available
diff --git a/docs/man/nng_stat.5.adoc b/docs/man/nng_stat.5.adoc
deleted file mode 100644
index 218bafb2..00000000
--- a/docs/man/nng_stat.5.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-= nng_stat(5)
-
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-
-== NAME
-
-nng_stat - statistic
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-----
-
-== DESCRIPTION
-
-An `nng_stat`(((statistic))) represents a statistic.
-All statistics have names (xref:nng_stat_name.3.adoc[`nng_stat_name()`]) and
-descriptions (xref:nng_stat_desc.3.adoc[`nng_stat_desc()`]), and are
-typed (xref:nng_stat_type.3.adoc[`nng_stat_type()`]).
-
-Most statistics are numeric,
-and thus carry a value (xref:nng_stat_value.3.adoc[`nng_stat_value()`])
-and frequently also a unit that the value measures (xref:nng_stat_unit.3.adoc[`nng_stat_unit()`]).
-
-Some statistics however, are simply strings (xref:nng_stat_string.3.adoc[`nng_stat_string()`]),
-and thus carry no numeric value.
-
-Statistics are organized as a tree, and any given statistic can have siblings
-(xref:nng_stat_next.3.adoc[`nng_stat_next()`]).
-Note however that generally only `NNG_STAT_SCOPE` statistics, which are
-act as placeholders in the tree (and carry no value),
-will have children (xref:nng_stat_child.3.adoc[`nng_stat_child()`]).
-
-A tree of statistics is collected using xref:nng_stats_get.3.adoc[`nng_stats_get()`],
-and can be freed when no longer needed with xref:nng_stats_free.3.adoc[`nng_stats_free()`].
-This collection process is generally performed in a way to minimize impact
-to running operations, but there is still some impact caused by collection
-of statistics.
-
-The time when a statistic's value is captured can be obtained using
-xref:nng_stat_timestamp.3.adoc[`nng_stat_timestamp()`], which is useful for
-measuring rates of change in certain statistics.
-
-NOTE: The presence, names, and meanings of any given statistic are
-subject to change at any time. These statistics are provided as an aid
-for debugging, and should generally not be relied upon for programmatic
-behaviors.
-
-NOTE: Statistics may be disabled by build-time configuration options,
-in order to reduce program size and run-time overheads.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stats_free.3.adoc[nng_stats_free(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat_child.3.adoc[nng_stat_child(3)],
-xref:nng_stat_desc.3.adoc[nng_stat_desc(3)],
-xref:nng_stat_find.3.adoc[nng_stat_find(3)],
-xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
-xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)],
-xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
-xref:nng_stat_name.3.adoc[nng_stat_name(3)],
-xref:nng_stat_next.3.adoc[nng_stat_next(3)],
-xref:nng_stat_string.3.adoc[nng_stat_string(3)],
-xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp(3)],
-xref:nng_stat_type.3.adoc[nng_stat_type(3)],
-xref:nng_stat_unit.3.adoc[nng_stat_unit(3)],
-xref:nng_stat_value.3.adoc[nng_stat_value(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_bool.3.adoc b/docs/man/nng_stat_bool.3.adoc
deleted file mode 100644
index 678b45aa..00000000
--- a/docs/man/nng_stat_bool.3.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-= nng_stat_bool(3)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_bool - get statistic Boolean value
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-bool nng_stat_bool(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_bool()` function returns the Boolean value for the statistic _stat_.
-Otherwise, if the statistic is not of Boolean type, the result is indeterminate.
-See xref:nng_stat_type.3.adoc[`nng_stat_type()`] for a description of statistic types.
-
-== RETURN VALUES
-
-The boolean value associated with _stat_.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat_type.3.adoc[nng_stat_type(3)],
-xref:nng_stat_unit.3.adoc[nng_stat_unit(3)],
-xref:nng_stat_value.3.adoc[nng_stat_value(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_child.3.adoc b/docs/man/nng_stat_child.3.adoc
deleted file mode 100644
index 123ca82d..00000000
--- a/docs/man/nng_stat_child.3.adoc
+++ /dev/null
@@ -1,51 +0,0 @@
-= nng_stat_child(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_child - get child statistic
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-nng_stat *nng_stat_child(nng_stat *parent);
-----
-
-== DESCRIPTION
-
-The `nng_stat_child()` function returns the first child statistic of the
-statistic _parent_.
-If no children are present, then `NULL` is returned.
-
-TIP: Only statistics with type (see xref:nng_stat_type.3.adoc[`nng_stat_type()`])
-of `NNG_STAT_SCOPE` will have children.
-
-== RETURN VALUES
-
-The first child statistic of _parent_, or NULL if _parent_ has no children.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stat_next.3.adoc[nng_stat_next(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_desc.3.adoc b/docs/man/nng_stat_desc.3.adoc
deleted file mode 100644
index e87849d3..00000000
--- a/docs/man/nng_stat_desc.3.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-= nng_stat_desc(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_desc - get statistic description
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-const char *nng_stat_desc(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_desc()` function returns a brief, human-readable description
-for the statistic _stat_.
-
-TIP: This description can be used for a tool-tip in user interfaces
-displaying these statistic values.
-
-NOTE: At this time, only English descriptions are provided.
-
-== RETURN VALUES
-
-The description of statistic _stat_.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stat_name.3.adoc[nng_stats_name(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_find.3.adoc b/docs/man/nng_stat_find.3.adoc
deleted file mode 100644
index cdcf461f..00000000
--- a/docs/man/nng_stat_find.3.adoc
+++ /dev/null
@@ -1,51 +0,0 @@
-= nng_stat_find(3)
-
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-
-== NAME
-
-nng_stat_find - find statistic by name
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-nng_stat *nng_stat_find(nng_stat *stat, const char *name);
-----
-
-== DESCRIPTION
-
-The `nng_stat_find()` function searches the statistics tree _stat_, looking for a statistic whose name is _name_.
-If it finds one, it returns it.
-Otherwise `NULL` is returned.
-
-NOTE: If multiple statistics have that name, then only the first match is returned.
-
-== RETURN VALUES
-
-The matching statistic, or NULL if no match is found.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stat_child.3.adoc[nng_stat_child(3)],
-xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
-xref:nng_stat_find_listener.3.adoc[nng_stat_find_listner(3)],
-xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_find_dialer.3.adoc b/docs/man/nng_stat_find_dialer.3.adoc
deleted file mode 100644
index 202fd289..00000000
--- a/docs/man/nng_stat_find_dialer.3.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-= nng_stat_find_dialer(3)
-
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-
-== NAME
-
-nng_stat_find_dialer - find dialer statistics
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-typedef struct nng_dialer nng_dialer;
-
-nng_stat *nng_stat_find_dialer(nng_stat *stat, nng_dialer dialer);
-----
-
-== DESCRIPTION
-
-The `nng_stat_find_dialer()` function returns the statistics tree within _stat_ associated with the dialer _dialer_, if such a tree exists.
-Otherwise `NULL` is returned.
-
-Generally, there will be child statistics of the returned value, each corresponding to a specific metric.
-These can be further scanned using either
-xref:nng_stat_find.3.adoc[nng_stat_find(3)]
-or by walking the tree with
-xref:nng_stat_child.3.adoc[nng_stat_child(3)].
-
-== RETURN VALUES
-
-The matching statistic, or NULL if no match is found.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stat_child.3.adoc[nng_stat_child(3)],
-xref:nng_stat_find.3.adoc[nng_stat_find(3)],
-xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)],
-xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_find_listener.3.adoc b/docs/man/nng_stat_find_listener.3.adoc
deleted file mode 100644
index 46c2dc74..00000000
--- a/docs/man/nng_stat_find_listener.3.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-= nng_stat_find_listener(3)
-
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-
-== NAME
-
-nng_stat_find_listener - find listener statistics
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-typedef struct nng_listener nng_listener;
-
-nng_stat *nng_stat_find_listener(nng_stat *stat, nng_listener listener);
-----
-
-== DESCRIPTION
-
-The `nng_stat_find_listener()` function returns the statistics tree within _stat_ associated with the listener _listener_, if such a tree exists.
-Otherwise `NULL` is returned.
-
-Generally, there will be child statistics of the returned value, each corresponding to a specific metric.
-These can be further scanned using either
-xref:nng_stat_find.3.adoc[nng_stat_find(3)]
-or by walking the tree with
-xref:nng_stat_child.3.adoc[nng_stat_child(3)].
-
-== RETURN VALUES
-
-The matching statistic, or NULL if no match is found.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stat_child.3.adoc[nng_stat_child(3)],
-xref:nng_stat_find.3.adoc[nng_stat_find(3)],
-xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
-xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_find_socket.3.adoc b/docs/man/nng_stat_find_socket.3.adoc
deleted file mode 100644
index deea509c..00000000
--- a/docs/man/nng_stat_find_socket.3.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-= nng_stat_find_socket(3)
-
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-
-== NAME
-
-nng_stat_find_socket - find socket statistics
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-typedef struct nng_socket nng_socket;
-
-nng_stat *nng_stat_find_socket(nng_stat *stat, nng_socket socket);
-----
-
-== DESCRIPTION
-
-The `nng_stat_find_socket()` function returns the statistics tree within _stat_ associated with the socket _socket_, if such a tree exists.
-Otherwise `NULL` is returned.
-
-Generally, there will be child statistics of the returned value, each corresponding to a specific metric.
-These can be further scanned using either
-xref:nng_stat_find.3.adoc[nng_stat_find(3)]
-or by walking the tree with
-xref:nng_stat_child.3.adoc[nng_stat_child(3)].
-
-== RETURN VALUES
-
-The matching statistic, or NULL if no match is found.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stat_child.3.adoc[nng_stat_child(3)],
-xref:nng_stat_find.3.adoc[nng_stat_find(3)],
-xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
-xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_name.3.adoc b/docs/man/nng_stat_name.3.adoc
deleted file mode 100644
index bf2fd3c7..00000000
--- a/docs/man/nng_stat_name.3.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-= nng_stat_name(3)
-
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-
-== NAME
-
-nng_stat_name - get statistic name
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-const char *nng_stat_name(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_name()` function returns the name for the statistic _stat_.
-
-NOTE: The global root statistic will have the empty string ("") as it's name.
-
-== RETURN VALUES
-
-The name of statistic _stat_.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_next.3.adoc b/docs/man/nng_stat_next.3.adoc
deleted file mode 100644
index 00caa5c8..00000000
--- a/docs/man/nng_stat_next.3.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-= nng_stat_next(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_next - get next statistic
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-nng_stat *nng_stat_next(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_next()` function returns the next sibling statistic of the
-statistic _stat_.
-If no more siblings are present, then `NULL` is returned.
-
-== RETURN VALUES
-
-The next sibling statistic of _stat_, or NULL if _stat_ is the last sibling.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stat_child.3.adoc[nng_stat_child(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_string.3.adoc b/docs/man/nng_stat_string.3.adoc
deleted file mode 100644
index 4c65fb1a..00000000
--- a/docs/man/nng_stat_string.3.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-= nng_stat_string(3)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_string - get statistic string value
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-const char *nng_stat_string(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_string()` function returns a string value for the statistic _stat_,
-which must be of type `NNG_STAT_STRING` (see xref:nng_stat_type.3.adoc[`nng_stat_type(3)`]).
-
-If the statistic is not of type `NNG_STAT_STRING`, then `NULL` will be returned.
-
-NOTE: The returned string is valid until xref:nng_stats_free.3.adoc[`nng_stats_free()`] is called to
-free the memory for the snapshot.
-
-== RETURN VALUES
-
-The string value associated with _stat_, or `NULL` if the statistic is not
-a string type.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat_type.3.adoc[nng_stats_type(3)],
-xref:nng_stat_value.3.adoc[nng_stats_value(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_timestamp.3.adoc b/docs/man/nng_stat_timestamp.3.adoc
deleted file mode 100644
index 74d827e8..00000000
--- a/docs/man/nng_stat_timestamp.3.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= nng_stat_timestamp(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_timestamp - get statistic timestamp
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-uint64_t nng_stat_timestamp(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_timestamp()` function returns the a timestamp, which is measured
-as a number of milliseconds since some arbitrary value in the past.
-
-Even within the same snapshot, statistics might have different timestamp
-values, as the timestamp represents the time when that particular statistic
-was captured.
-
-TIP: These values are intended to facilitate calculation of rates, by
-comparing values from one snapshot with a subsequent one.
-
-TIP: The values used here have the same offset as the
-xref:nng_clock.3supp.adoc[`nng_clock()`] supplemental function.
-This can be useful when converting these values to local clock time.
-
-== RETURN VALUES
-
-The timestamp when _stat_ was captured, measured as a number of
-milliseconds since some time in the past.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat_value.3.adoc[nng_stat_value(3)],
-xref:nng_clock.3supp.adoc[nng_clock(3supp)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_type.3.adoc b/docs/man/nng_stat_type.3.adoc
deleted file mode 100644
index a2578e5e..00000000
--- a/docs/man/nng_stat_type.3.adoc
+++ /dev/null
@@ -1,95 +0,0 @@
-= nng_stat_type(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_type - get statistic type
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-enum {
-        NNG_STAT_SCOPE,
-        NNG_STAT_LEVEL,
-        NNG_STAT_COUNTER,
-        NNG_STAT_STRING,
-        NNG_STAT_BOOLEAN,
-        NNG_STAT_ID
-};
-
-int nng_stat_type(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_type()` function returns the type of the statistic _stat_.
-
-The returned type will be one of the following values:
-
-((`NNG_STAT_SCOPE`))::
-This is a placeholder providing scope, and carries no value on its own.
-Instead it is a parent node with child statistics (see
-xref:nng_stat_child.3.adoc[`nng_stat_child()`].)
-
-((`NNG_STAT_LEVEL`))::
-This is a numeric statistic, but its value is a level, so rate calculations
-based on changes in this value should not be considered significant.
-
-((`NNG_STAT_COUNTER`))::
-This is a numeric statistic that represents an increasing count, typically
-of events, messages, or bytes.
-Frequently, it is interesting to consider changes in this statistic divided
-by time to obtain a rate.
-(For example, throughput might be calculated as changes in a byte counter
-divided by the interval over which the change occurred.)
-
-((`NNG_STAT_STRING`))::
-This is a string, and carries no numeric value.
-Instead the xref:nng_stat_string.3.adoc[`nng_stat_string()`] function
-should be used to obtain the value.
-
-((`NNG_STAT_BOOLEAN`))::
-This is a boolean value.
-The xref:nng_stat_value.3.adoc[`nng_stat_value()`] function will return zero
-to represent a `false` value, and one to represent a `true` value.
-
-((`NNG_STAT_ID`)):
-The statistic is a numeric ID.
-These are generally immutable values that represent an identity that might
-be used with another interface.
-
-TIP: For `NNG_STAT_COUNTER` and `NNG_STAT_LEVEL` statistics, the
-xref:nng_stat_unit.3.adoc[`nng_stat_unit()`] function will provide more
-detail about the units measured by the static.
-
-== RETURN VALUES
-
-The statistic type for _stat_.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat_string.3.adoc[nng_stat_string(3)],
-xref:nng_stat_unit.3.adoc[nng_stat_unit(3)],
-xref:nng_stat_value.3.adoc[nng_stat_value(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_unit.3.adoc b/docs/man/nng_stat_unit.3.adoc
deleted file mode 100644
index f7136e1f..00000000
--- a/docs/man/nng_stat_unit.3.adoc
+++ /dev/null
@@ -1,86 +0,0 @@
-= nng_stat_unit(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_unit - get statistic unit
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-enum {
-        NNG_UNIT_NONE,
-        NNG_UNIT_BYTES,
-        NNG_UNIT_MESSAGES,
-        NNG_UNIT_MILLIS,
-        NNG_UNIT_EVENTS
-};
-
-int nng_stat_unit(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_unit()` function returns the unit of quantity measured
-by the statistic _stat_.
-
-The returned value will be one of the following values:
-
-((`NNG_UNIT_NONE`))::
-There are no particular units measured.
-In some cases there may be units, but the type of the unit will be obvious
-from the name (see xref:nng_stat_name.3.adoc[`nng_stat_name()`]) of the statistic.
-
-((`NNG_UNIT_BYTES`))::
-The statistic is a count of bytes.
-
-((`NNG_UNIT_MESSAGES`))::
-The statistic is a count of messages.
-Typically, one message corresponds to a single xref:nng_msg.5.adoc[`nng_msg`] structure.
-
-((`NNG_UNIT_MILLIS`))::
-The statistic is a count of milliseconds.
-
-((`NNG_STAT_EVENTS`))::
-The statistic is a count of some other type of event.
-
-For statistics that are neither `NNG_STAT_COUNTER` nor `NNG_STAT_LEVEL`
-type (see xref:nng_stat_type.3.adoc[`nng_stat_type()`]), the unit will
-generally be `NNG_UNIT_NONE`.
-
-TIP: Normally rates can be calculated for `NNG_STAT_COUNTER` values for
-any of these units, but for `NNG_UNIT_MILLIS` rate calculations are generally
-meaningless.
-
-== RETURN VALUES
-
-The units measured by _stat_.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat_name.3.adoc[nng_stat_name(3)],
-xref:nng_stat_type.3.adoc[nng_stat_type(3)],
-xref:nng_stat_value.3.adoc[nng_stat_value(3)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stat_value.3.adoc b/docs/man/nng_stat_value.3.adoc
deleted file mode 100644
index d5d28473..00000000
--- a/docs/man/nng_stat_value.3.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-= nng_stat_value(3)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stat_value - get statistic numeric value
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-uint64_t nng_stat_value(nng_stat *stat);
-----
-
-== DESCRIPTION
-
-The `nng_stat_value()` function returns a numeric value for the statistic _stat_.
-If the statistic is not of numeric type, then zero is returned.
-See xref:nng_stat_type.3.adoc[`nng_stat_type()`] for a description of statistic types.
-
-== RETURN VALUES
-
-The numeric value associated with _stat_.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng_stats_get.3.adoc[nng_stats_get(3)],
-xref:nng_stat_bool.3.adoc[nng_stat_bool(3)],
-xref:nng_stat_type.3.adoc[nng_stat_type(3)],
-xref:nng_stat_unit.3.adoc[nng_stat_unit(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_stats_get.3.adoc b/docs/man/nng_stats_get.3.adoc
deleted file mode 100644
index 5cbb2624..00000000
--- a/docs/man/nng_stats_get.3.adoc
+++ /dev/null
@@ -1,86 +0,0 @@
-= nng_stats_get(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_stats_get - get statistics snapshot
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-int nng_stats_get(nng_stat **statsp)
-----
-
-== DESCRIPTION
-
-The `nng_stat_get()` function attempts to obtain a snapshot of all the
-various diagnostic statistics that are present in the system.
-
-NOTE: The process of collecting statistics is designed to have minimal
-impact on the system, but there is still some impact.
-
-The statistics are organized as a tree, rooted with a parent
-statistic of type `NNG_STAT_SCOPE` that carries no value, and which
-has an empty name.
-This parent statistic is returned through the _statsp_ pointer.
-
-The xref:nng_stat_child.3.adoc[`nng_stat_child()`] and
-xref:nng_stat_next.3.adoc[`nng_stat_next()`] function can be used to
-iterate over the the tree.
-
-When no longer needed, the statistics can be freed with the
-xref:nng_stats_free.3.adoc[`nng_stats_free()`] function, but that
-function must be called only with the root statistic that is returned
-through the _statsp_ pointer.
-
-NOTE: The values of individual statistics are guaranteed to be atomic,
-but due the way statistics are collected there can be discrepancies between them at certain times.
-For example, statistics counting bytes and messages received may not
-reflect the same number of messages, depending on when the snapshot is taken.
-This potential inconsistency arises as a result of optimizations to minimize
-the impact of statistics on actual operations.
-
-NOTE: The names, values, and semantics of statistics provided may change
-from release to release.
-These are provided for informational and debugging use only, and applications
-should not rely on the presence, names, or meanings of any individual statistics.
-
-== RETURN VALUES
-
-This function returns a pointer to the allocated memory on success,
-and `NULL` otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory to collect statistics.
-`NNG_ENOTSUP`:: Statistics are not supported (compile time option).
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_stats_free.3.adoc[nng_stats_free(3)],
-xref:nng_stat_child.3.adoc[nng_stat_child(3)],
-xref:nng_stat_desc.3.adoc[nng_stat_desc(3)],
-xref:nng_stat_name.3.adoc[nng_stat_name(3)],
-xref:nng_stat_next.3.adoc[nng_stat_next(3)],
-xref:nng_stat_string.3.adoc[nng_stat_string(3)],
-xref:nng_stat_type.3.adoc[nng_stat_type(3)],
-xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp(3)],
-xref:nng_stat_unit.3.adoc[nng_stat_unit(3)],
-xref:nng_stat_value.3.adoc[nng_stat_value(3)],
-xref:nng_stat.5.adoc[nng_stat(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index 094eac11..b0dd9f51 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -26,6 +26,11 @@
     - [nng_log_level](./api/log/nng_log_level.md)
     - [nng_log_logger](./api/log/nng_log_logger.md)
 
+  - [Statistics](./api/stat/index.md)
+
+    - [nng_stat](./api/stat/nng_stat.md)
+    - [nng_stats](./api/stat/nng_stats.md)
+
   - [Utility Functions](./api/util/index.md)
 
     - [nng_alloc](./api/util/nng_alloc.md)
diff --git a/docs/ref/api/stat/index.md b/docs/ref/api/stat/index.md
new file mode 100644
index 00000000..9bdceb55
--- /dev/null
+++ b/docs/ref/api/stat/index.md
@@ -0,0 +1,23 @@
+# Statistics
+
+To facilitate debugging and support situations, the _NNG_ library
+supports collection and reporting of numerous statistics.
+
+These statistics are organized in a tree, and include both values,
+and metadata describing the statistics. In order to be efficient and
+minimize the impact of maintaining statistics, an explicit snapshot
+of statistics must be taken, and that snapshot can then be processed.
+
+The following documentation will be useful:
+
+- [nng_stat](./nng_stat.md) - Single statistic
+- [nng_stats](./nng_stats.md) - Statistics snapshot
+
+> [!NOTE]
+> The presence, name, and semantics of any given statistic are
+> subject to change at any time and without notice.
+> Programmatic use is therefore discouraged.
+
+> [!NOTE]
+> Statistics may be disabled by build-time configuration options,
+> in order to reduce program size and run-time overheads.
diff --git a/docs/ref/api/stat/nng_stat.md b/docs/ref/api/stat/nng_stat.md
new file mode 100644
index 00000000..7010ac0b
--- /dev/null
+++ b/docs/ref/api/stat/nng_stat.md
@@ -0,0 +1,110 @@
+# nng_stat
+
+## NAME
+
+nng_stat --- statistic
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+enum {
+	NNG_STAT_SCOPE,
+	NNG_STAT_LEVEL,
+	NNG_STAT_COUNTER,
+	NNG_STAT_STRING,
+	NNG_STAT_BOOLEAN,
+	NNG_STAT_ID
+};
+
+enum {
+	NNG_UNIT_NONE,
+	NNG_UNIT_BYTES,
+	NNG_UNIT_MESSAGES,
+	NNG_UNIT_MILLIS,
+	NNG_UNIT_EVENTS
+};
+
+int nng_stat_unit(nng_stat *stat);
+
+const char *nng_stat_name(nng_stat *stat);
+const char *nng_stat_desc(nng_stat *stat);
+int nng_stat_type(nng_stat *stat);
+int nng_stat_unit(nng_stat *stat);
+uint64_t nng_stat_value(nng_stat *stat);
+const char *nng_stat_string(nng_stat *stat);
+bool nng_stat_bool(nng_stat *stat);
+uint64_t nng_stat_timestamp(nng_stat *stat);
+```
+
+## DESCRIPTION
+
+An {{i:`nng_stat`}} represents a {{i:statistic}}.
+All statistics have names (retrievable with {{i:`nng_stat_name`}}) and
+descriptions (retrievable with {{i:`nng_stat_desc`}}), and a
+type (retrievable with {{i:`nng_stat_type`}}).
+
+Statistics also have a timestamp indicating when the value was sampled,
+obtained via {{i:`nng_stat_timestamp}}`. The timestamp is given in
+in milliseconds since a reference time, and the reference time used
+here is the same reference time used for [`nng_clock`][nng_clock].
+
+> [!NOTE]
+> The presence, name, and semantics of any given statistic are
+> subject to change at any time and without notice.
+
+### Statistic Values
+
+The type of a statistic determines the nature of the value, and which
+function can be used to obtain that value.
+
+- {{i:`NNG_STAT_SCOPE`}}: The statistic does not carry any real value, but is
+  used for grouping related statistics together. This is a nexus in the
+  statistics tree.
+
+- {{i:`NNG_STAT_COUNTER`}}: The statistic is a counter that only increments.
+  Usually the change in the value of the statistic is more interesting
+  (as a rate) than the absolute value at any given time. The value should
+  be obtained using `nng_stat_value`. The units will be given by the value
+  returned from `nng_stat_unit`.
+
+- {{i:`NNG_STAT_LEVEL`}}: The statistic represnts a measured value which corresponds
+  to a specific value at a specific time. For example, this may represent the
+  number of messages currently queued for some operation, or the link speed
+  of a network interface. Most often the absolute value is more interesting
+  than the change in the value over time. Again the value can be obtained with
+  `nng_stat_value`, and any appropriate unit of measurement with `nng_stat_unit`.
+
+- {{i:`NNG_STAT_STRING`}}: The statistic is a string, such as a human. The value
+  of the string can be obtained with `nng_stat_string`. The value of this string
+  will remain valid until the snapshot is deallocated with [`nng_stats_free`][nng_stats].
+
+- {{i:`NNG_STAT_BOOLEAN`}}: The value of the statistic is a truth value (either `true`
+  or `false`) and can be obtained with `nng_stat_bool`.
+
+- {{i:`NNG_STAT_ID`}}: The value of the statistic is a numeric identifier, such as a socket
+  identifier. The value can be obtained with `nng_stat_value`, and will generally not
+  change over time for a given statistic.
+
+### Statistic Units
+
+For statistics of type `NNG_STAT_COUNTER` or `NNG_STAT_LEVEL`, it is often
+useful to know what that quantity being reported actually measures.
+The following units may be returned from `nng_stat_unit` for such a statistic:
+
+- `NNG_UNIT_NONE`: No unit is known or applies.
+- `NNG_UNIT_BYTES`: A count of bytes.
+- `NNG_UNIT_MESSAGES`: A count of messages.
+- `NNG_UNIT_MILLIS`: A count of milliseconds.
+- `NNG_UNIT_EVENTS`: A count of events of some type.
+
+## SEE ALSO
+
+[nng_clock][nng_clock],
+[nng_stats][nng_stats],
+
+[nng_clock]: ../util/nng_clock.md
+[nng_stats]: ./nng_stats.md
diff --git a/docs/ref/api/stat/nng_stats.md b/docs/ref/api/stat/nng_stats.md
new file mode 100644
index 00000000..a932ca5d
--- /dev/null
+++ b/docs/ref/api/stat/nng_stats.md
@@ -0,0 +1,107 @@
+# nng_stats
+
+## NAME
+
+nng_stats --- statistics snapshot
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+
+int nng_stats_get(nng_stat **statsp);
+void nng_stats_free(nng_stat *stats);
+nng_stat *nng_stat_next(nng_stat *stat);
+nng_stat *nng_stat_find(nng_stat *stat, const char *name);
+nng_stat *nng_stat_find_dialer(nng_stat *stat, nng_dialer dialer);
+nng_stat *nng_stat_find_listener(nng_stat *stat, nng_dialer listener);
+nng_stat *nng_stat_find_socket(nng_stat *stat, nng_dialer socket);
+```
+
+## DESCRIPTION
+
+Statistics maintained by the system are organized in a tree, and
+a snapshot of all statistics can be taken, and then traversed
+and searched.
+
+### Statistics Snapshot Collection
+
+The {{i:`nng_stats_get`}} function attempts to obtain a snapshot of all the
+various diagnostic statistics that are present in the system.
+On success, a pointer to the statistics tree snapshot is returned in _statsp_.
+
+> [!NOTE]
+> The process of collecting statistics is designed to have minimal
+> impact on the system, but there is still some impact.
+
+The statistics are organized as a tree, rooted with a parent
+statistic of type `NNG_STAT_SCOPE` that carries no value, and which
+has an empty name.
+This parent statistic is returned through the _statsp_ pointer.
+
+When no longer needed, the statistics snapshot can be freed with the
+{{i:`nng_stats_free`}} function.
+
+> [!IMPORTANT]
+> The `nng_stats_free` function must be called only with the root statistic that is
+> returned through the _statsp_ pointer.
+
+> [!NOTE]
+> The values of individual statistics are guaranteed to be atomic,
+> but due the way statistics are collected there can be discrepancies between
+> them at certain times.
+> For example, statistics counting bytes and messages received may not
+> reflect the same number of messages, depending on when the snapshot is taken.
+> This potential inconsistency arises as a result of optimizations to minimize
+> the impact of statistics on actual operations.
+
+### Traversing the Statistics Tree
+
+Traversing the tree of statistics is done using the `nng_stat_child` and
+`nng_stat_next` functions.
+
+The `nng_stat_child` function returns either the first child of _stat_,
+or `NULL` if the _stat_ has no children.
+
+The `nng_stat_next` function returns the nearest sibling to the right of _stat_,
+or `NULL` if _stat_ has no more siblings to the right.
+
+### Finding a Statistic
+
+Sometimes it is easiest to search for a specific statistic, matching by name,
+or possibly to find the tree of statistics associated iwth a specific [socket][nng_socket],
+[dialer][nng_dialer], or [listener][nng_listener].
+
+The `nng_stat_find` functions are provided for this purpose.
+
+The `nng_stat_find` function returns the first statistic within the subtree of
+statistics _stat_, with the given _name_. If no such statistic can be found, `NULL`
+is returned.
+
+The `nng_stat_find_dialer`, `nng_stat_find_listener`, and `nng_stat_find_socket` return
+the statistics subtree for the given dialer, listener, or socket object. Note that
+these functions should be provided the root of the statistic tree, in order to ensure
+that they can find the desired object.
+
+## RETURN VALUES
+
+The `nng_stats_get` function returns zero on success, or a non-zero error value on failure.
+
+Aside from `nng_stats_free`, which has no return, the remaining functions return a pointer to
+the desired statistic object, or `NULL` if such a statistic cannot be found.
+
+## ERRORS
+
+- `NNG_ENOMEM`: Insufficient free memory to collect statistics.
+- `NNG_ENOTSUP`: Statistics are not supported (compile time option).
+
+## SEE ALSO
+
+[nng_stat][nng_stat]
+
+[nng_stat]: ./nng_stat.md
+[nng_socket]: TODO.md
+[nng_dialer]: TODO.md
+[nng_listener]: TODO.md