From 7b94afaa6669bc915ddf153816a0803bc3383fac Mon Sep 17 00:00:00 2001
From: William Hobbs <13199119+wihobbs@users.noreply.github.com>
Date: Sat, 16 Dec 2023 00:29:22 +0000
Subject: [PATCH] docs: add flux_msg_incref manpage

Problem: there's no RTD documentation for flux_msg_incref, which
is a useful function for streaming RPCs.

Add it.
---
 doc/Makefile.am              |  5 +++
 doc/man3/flux_msg_create.rst | 67 ++++++++++++++++++++++++++++++++++++
 doc/manpages.py              |  5 +++
 3 files changed, 77 insertions(+)
 create mode 100644 doc/man3/flux_msg_create.rst

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a4abfa7ef257..71202673befc 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -112,6 +112,7 @@ MAN3_FILES_PRIMARY = \
 	man3/flux_idle_watcher_create.3 \
 	man3/flux_msg_handler_create.3 \
 	man3/flux_msg_cmp.3 \
+	man3/flux_msg_create.3 \
 	man3/flux_msg_handler_addvec.3 \
 	man3/flux_child_watcher_create.3 \
 	man3/flux_signal_watcher_create.3 \
@@ -245,6 +246,10 @@ MAN3_FILES_SECONDARY = \
 	man3/flux_future_or_then.3 \
 	man3/flux_future_continue.3 \
 	man3/flux_future_continue_error.3 \
+	man3/flux_msg_copy.3 \
+	man3/flux_msg_incref.3 \
+	man3/flux_msg_decref.3 \
+	man3/flux_msg_destroy.3 \
 	man3/flux_rpc_pack.3 \
 	man3/flux_rpc_raw.3 \
 	man3/flux_rpc_message.3 \
diff --git a/doc/man3/flux_msg_create.rst b/doc/man3/flux_msg_create.rst
new file mode 100644
index 000000000000..2e0dfa43c05a
--- /dev/null
+++ b/doc/man3/flux_msg_create.rst
@@ -0,0 +1,67 @@
+==========================
+flux_msg_create(3)
+==========================
+
+.. default-domain:: c
+
+SYNOPSIS
+========
+
+.. code-block:: c
+
+   #include <flux/core.h>
+
+   flux_msg_t *flux_msg_create (int type)
+
+   flux_msg_t *flux_msg_copy (const flux_msg_t *msg, bool payload)
+
+   const flux_msg_t *flux_msg_incref (const flux_msg_t *const_msg)
+
+   void flux_msg_decref (const flux_msg_t *const_msg)
+
+   void flux_msg_destroy (flux_msg_t *msg)
+
+
+DESCRIPTION
+===========
+
+:func:`flux_msg_create` creates a `flux_msg_t` of `int type`. Different types
+of Flux messages are defined `RFC 6 <https://flux-framework.readthedocs.io/
+projects/flux-rfc/en/latest/spec_6.html>_`.
+
+:func:`flux_msg_copy` copies the attributes of a `flux_msg_t` object into a new
+`flux_msg_t` object.
+
+:func:`flux_msg_incref` provides a constant pointer to a `flux_msg_t` object.
+It also increments the reference count of the object by 1.
+
+:func:`flux_msg_decref` decrements the reference count of a `flux_msg_t` object
+by 1. When the reference count reaches 0, the message is destroyed.
+
+:func:`flux_msg_destroy` destroys a message.
+
+RETURN VALUE
+============
+
+:func:`flux_msg_create` returns a `flux_msg_t` type.
+
+:func:`flux_msg_copy` returns a new `flux_msg_t` object with the same attributes
+as another `flux_msg_t` objects.
+
+:func:`flux_msg_incref` returns a constant pointer to a `flux_msg_t` object.
+
+:func:`flux_msg_decref` has no return value.
+
+:func:`flux_msg_destroy` has no return value.
+
+
+RESOURCES
+=========
+
+.. include:: common/resources.rst
+
+
+SEE ALSO
+========
+
+:man3:`flux_send`, :man3:`flux_respond`
diff --git a/doc/manpages.py b/doc/manpages.py
index 2bfd88070c30..552dedd3e142 100644
--- a/doc/manpages.py
+++ b/doc/manpages.py
@@ -165,6 +165,11 @@
     ('man3/flux_log', 'flux_log_set_procid', 'Log messages to the Flux Message Broker', [author], 3),
     ('man3/flux_log', 'flux_log', 'Log messages to the Flux Message Broker', [author], 3),
     ('man3/flux_msg_cmp', 'flux_msg_cmp', 'match a message', [author], 3),
+    ('man3/flux_msg_create', 'flux_msg_create', 'create a Flux message', [author], 3),
+    ('man3/flux_msg_create', 'flux_msg_copy', 'copy a Flux message\'s attributes into a new Flux message', [author], 3),
+    ('man3/flux_msg_create', 'flux_msg_incref', 'get a memory address for a Flux message and increment reference count', [author], 3),
+    ('man3/flux_msg_create', 'flux_msg_decref', 'decrement the reference count of a Flux message by 1', [author], 3),
+    ('man3/flux_msg_create', 'flux_msg_destroy', 'destroy a Flux message when reference count reaches 0', [author], 3),
     ('man3/flux_msg_encode', 'flux_msg_decode', 'convert a Flux message to buffer and back again', [author], 3),
     ('man3/flux_msg_encode', 'flux_msg_encode', 'convert a Flux message to buffer and back again', [author], 3),
     ('man3/flux_msg_handler_addvec', 'flux_msg_handler_delvec', 'bulk add/remove message handlers', [author], 3),