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

@@ -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 \

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`

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),