flux_watcher_start(3): document ref/unref methods

Problem: flux_watcher_ref(), flux_watcher_unref(), and
flux_watcher_is_referenced() are undocumented.

Update man pages.

doc/Makefile.am

@@ -208,6 +208,9 @@ MAN3_FILES_SECONDARY = \
 	man3/flux_watcher_stop.3 \
 	man3/flux_watcher_is_active.3 \
 	man3/flux_watcher_destroy.3 \
+	man3/flux_watcher_ref.3 \
+	man3/flux_watcher_unref.3 \
+	man3/flux_watcher_is_referenced.3 \
 	man3/flux_watcher_next_wakeup.3 \
 	man3/flux_handle_watcher_get_flux.3 \
 	man3/flux_timer_watcher_reset.3 \

doc/man3/flux_watcher_start.rst

@@ -15,6 +15,12 @@ SYNOPSIS
 
   bool flux_watcher_is_active (flux_watcher_t *w);
 
+  void flux_watcher_unref (flux_watcher_t *w);
+
+  void flux_watcher_ref (flux_watcher_t *w);
+
+  bool flux_watcher_is_referenced (flux_watcher_t *w);
+
   void flux_watcher_destroy (flux_watcher_t *w);
 
   double flux_watcher_next_wakeup (flux_watcher_t *w);
@@ -36,6 +42,16 @@ callback.
 :func:`flux_watcher_is_active` returns a true value if the watcher is active
 (i.e. it has been started and not yet stopped) and false otherwise.
 
+:func:`flux_watcher_unref` ensures that when the watcher is active, it doesn't
+prevent the reactor from exiting.  This function is idempotent.
+
+:func:`flux_watcher_ref` reverses :func:`flux_watcher_unref`.  This function
+is idempotent.
+
+:func:`flux_watcher_is_referenced` returns true if the watcher is referenced.
+All watchers are referenced unless this is changed with
+:func:`flux_watcher_unref` is called on them.
+
 :func:`flux_watcher_destroy` destroys a :type:`flux_watcher_t` object :var:`w`,
 after stopping it. It is not safe to destroy a watcher object within a
 :type:`flux_watcher_f` callback.

doc/manpages.py

@@ -280,11 +280,14 @@
     ('man3/flux_stat_watcher_create', 'flux_stat_watcher_create', 'create stat watcher', [author], 3),
     ('man3/flux_timer_watcher_create', 'flux_timer_watcher_reset', 'set/reset a timer', [author], 3),
     ('man3/flux_timer_watcher_create', 'flux_timer_watcher_create', 'set/reset a timer', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_stop', 'start/stop/destroy/query reactor watcher', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_is_active', 'start/stop/destroy/query reactor watcher', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_destroy', 'start/stop/destroy/query reactor watcher', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_next_wakeup', 'start/stop/destroy/query reactor watcher', [author], 3),
-    ('man3/flux_watcher_start', 'flux_watcher_start', 'start/stop/destroy/query reactor watcher', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_stop', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_is_active', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_destroy', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_next_wakeup', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_start', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_ref', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_unref', 'common reactor watcher methods', [author], 3),
+    ('man3/flux_watcher_start', 'flux_watcher_is_referenced', 'common reactor watcher methods', [author], 3),
     ('man3/flux_watcher_set_priority', 'flux_watcher_set_priority', 'set watcher priority', [author], 3),
     ('man3/hostlist_create', 'hostlist_create', 'Manipulate lists of hostnames', [author], 3),
     ('man3/hostlist_create', 'hostlist_destroy', 'Manipulate lists of hostnames', [author], 3),

doc/test/spell.en.pws

@@ -939,3 +939,4 @@ aTGTz
 cPATH
 SATTR
 myprogram
+unref