Doc tweaking (#261)

* Fix typo: p{rr -> r}ocess
* doc: qbrb.h: several fixes to punctuation
* doc: qbrb.h: reindent example writer's error label as per reader
* doc: qbhdb.h: explain former importance to libqb itself
* doc: ipcc.c: explain why client would timebox recv from server
          Also refer to commit d633b4e.
* doc: qblog.h: minor stylistic/doxygen markup cosmetics
* doc: qblog.h: note qb_log_format_set vs. fork interaction wrt. PIDs

Signed-off-by: Jan Pokorný <[email protected]>

include/qb/qbhdb.h

@@ -39,6 +39,11 @@ extern "C" {
 /**
  * @file qbhdb.h
  * The handle database is for reference counting objects.
+ *
+ * @note
+ * Historically, handle database implementation also served internal needs
+ * of libqb (e.g. for IPC services tracking), which was eventually replaced
+ * with indirection-less reference counters and their direct modifications.
  */
 
 /**

include/qb/qblog.h

@@ -535,7 +535,7 @@ void qb_log_callsites_dump(void);
  *
  * @param target QB_LOG_SYSLOG, QB_LOG_STDERR or result from qb_log_file_open()
  * @param conf_type configuration directive ("what to configure") that accepts
- *        <tt>int32_t</tt> argument determining the new value unless ignored
+ *        @c int32_t argument determining the new value unless ignored
  *        for particular directive altogether
  *        (incompatible directives: QB_LOG_CONF_IDENT)
  * @param arg the new value for a state-changing configuration directive,
@@ -558,7 +558,7 @@ typedef union {
  *
  * @param target QB_LOG_SYSLOG, QB_LOG_STDERR or result from qb_log_file_open()
  * @param conf_type configuration directive ("what to configure") that accepts
- *        either <tt>int32_t</tt> or a null-terminated string argument
+ *        either @c int32_t or a null-terminated string argument
  *        determining the new value unless ignored for particular directive
  *        (compatible directives: those valid for qb_log_ctl
  *                                + QB_LOG_CONF_IDENT)
@@ -569,9 +569,9 @@ typedef union {
  *        that original function directly as it allows for more type safety)
  * @see qb_log_ctl
  *
- * @note You can use <tt>QB_LOG_CTL2_I32</tt> and <tt>QB_LOG_CTL2_S</tt>
- *       macros for a convenient on-the-fly construction of the object
- *       to be passed as an <tt>arg</tt> argument.
+ * @note You can use @ref QB_LOG_CTL2_I32 and @ref QB_LOG_CTL2_S macros
+ *       for a convenient on-the-fly construction of the object
+ *       to be passed as an @p arg argument.
  */
 int32_t qb_log_ctl2(int32_t target, enum qb_log_conf conf_type,
 		    qb_log_ctl2_arg_t arg);
@@ -640,7 +640,15 @@ void qb_log_tags_stringify_fn_set(qb_log_tags_stringify_fn fn);
  * %P PID
  * %H hostname
  *
- * any number between % and character specify field length to pad or chop
+ * Any number between % and character specify field length to pad or chop.
+ *
+ * @note Some of the fields are immediately evaluated and remembered
+ *       for performance reasons, so when there's an objective for log
+ *       messages to carry PIDs (not in the default setup) and, moreover,
+ *       precisely, this function needs to be reinvoked upon @c fork
+ *       (@c clone) in the respective children.  When already linking
+ *       to @c libpthread, @c pthread_atfork callback registration
+ *       could be useful.
  */
 void qb_log_format_set(int32_t t, const char* format);
 
@@ -707,13 +715,13 @@ void qb_log_custom_close(int32_t t);
 void *qb_log_target_user_data_get(int32_t t);
 
 /**
- * Associate user data with this log target
+ * Associate user data with this log target.
  * @note only use this with custom targets
  */
 int32_t qb_log_target_user_data_set(int32_t t, void *user_data);
 
 /**
- * format the callsite and timestamp info according to the format
+ * Format the callsite and timestamp info according to the format.
  * set using qb_log_format_set()
  * It is intended to be used from your custom logger function.
  */

include/qb/qbrb.h

@@ -32,21 +32,21 @@ extern "C" {
 
 /**
  * @file qbrb.h
- * This implements a ring buffer that works in "chunks" not bytes.
+ * This implements a ring buffer that works in "chunks", not bytes.
  * So you write/read a complete chunk or not at all.
- * There are two types of ring buffer normal and overwrite.
+ * There are two types of ring buffer: normal and overwrite.
  * Overwrite will reclaim the oldest chunks inorder to make way for new ones,
  * the normal version will refuse to write a new chunk if the ring buffer
  * is full.
  *
  * This implementation is capable of working across processes, but one process
- * must only write and the other prrocess read.
+ * must only write and the other process read.
  *
  * The read process will do the following:
  * @code
  *	rb = qb_rb_open("test2", 2000, QB_RB_FLAG_SHARED_PROCESS|QB_RB_FLAG_CREATE);
  *	for (i = 0; i < 200; i++) {
- *	try_read_again:
+ * try_read_again:
  *		l = qb_rb_chunk_read(rb, (void *)out, 32, 1000);
  *		if (l < 0) {
  *			goto try_read_again;
@@ -75,7 +75,7 @@ extern "C" {
  */
 
 /**
- * create a ring buffer (rather than open and existing one)
+ * Create a ring buffer (rather than open and existing one).
  * @see qb_rb_open()
  */
 #define QB_RB_FLAG_CREATE		0x01
@@ -126,7 +126,7 @@ qb_ringbuffer_t *qb_rb_open(const char *name, size_t size, uint32_t flags,
 			    size_t shared_user_data_size);
 
 /**
- * Dereference the ringbuffer and if we are the last user destroy it.
+ * Dereference the ringbuffer and, if we are the last user, destroy it.
  *
  * All files, mmaped memory, semaphores and locks will be destroyed.
  *
@@ -184,7 +184,7 @@ ssize_t qb_rb_chunk_write(qb_ringbuffer_t * rb, const void *data, size_t len);
 void *qb_rb_chunk_alloc(qb_ringbuffer_t * rb, size_t len);
 
 /**
- * finalize the chunk.
+ * Finalize the chunk.
  * @param rb ringbuffer instance
  * @param len (in) the size of the chunk.
  */
@@ -277,7 +277,7 @@ ssize_t qb_rb_write_to_file(qb_ringbuffer_t * rb, int32_t fd);
 qb_ringbuffer_t *qb_rb_create_from_file(int32_t fd, uint32_t flags);
 
 /**
- * Like 'chown' it changes the owner and group of the ringbuffers
+ * Like 'chown', it changes the owner and group of the ringbuffer's
  * resources.
  * @param owner uid of the owner to change to
  * @param group gid of the group to change to
@@ -287,7 +287,7 @@ qb_ringbuffer_t *qb_rb_create_from_file(int32_t fd, uint32_t flags);
 int32_t qb_rb_chown(qb_ringbuffer_t * rb, uid_t owner, gid_t group);
 
 /**
- * Like 'chmod' it changes the mode of the ringbuffers resources.
+ * Like 'chmod', it changes the mode of the ringbuffer's resources.
  * @param mode mode to change to
  * @param rb ringbuffer instance
  * @retval 0 == ok

lib/ipcc.c

@@ -323,6 +323,8 @@ qb_ipcc_sendv_recv(qb_ipcc_connection_t * c,
 	}
 
 	do {
+		/* following is a liveness-driven interleaving
+		   (for cases the server side failed/exited) */
 		if (timeout_rem > QB_IPC_MAX_WAIT_MS || ms_timeout == -1) {
 			timeout_now = QB_IPC_MAX_WAIT_MS;
 		} else {