update document for utils

util/array.h

@@ -1,16 +1,10 @@
 // No copyright
-#pragma once
-
-#include <assert.h>
-#include <stdint.h>
-#include <string.h>
-
-#include "util/malloc.h"
-
-
+//
+// Array util is a template macro of an array type.
+//
 // HOW TO USE
-//   To use an array, you must prepare an array struct, and use its functions for
-//   any operations to the array.
+//   To use an array, you must prepare an array struct, and use its functions
+//   for any operations to the array.
 //
 //   When you need an array of integers, the following array structs are
 //   available:
@@ -32,6 +26,14 @@
 //   You can see declarations of the functions on a definition of
 //   NF7UTIL_ARRAY_DECL macro. They all are prefixed by a name of your array
 //   struct.
+//
+#pragma once
+
+#include <assert.h>
+#include <stdint.h>
+#include <string.h>
+
+#include "util/malloc.h"
 
 
 #define NF7UTIL_ARRAY_TYPE(PREFIX, T)  \

util/buffer.h

@@ -1,4 +1,8 @@
 // No copyright
+//
+// nf7util_buffer is a generic buffer object which can be shared between
+// multiple owners. Only a unique owner can modify the buffer contents.
+//
 #pragma once
 
 #include <stdint.h>
@@ -8,9 +12,6 @@
 #include "util/refcnt.h"
 
 
-// nf7util_buffer is a generic buffer object which can be shared between
-// multiple owners. Only a unique owner can modify the buffer contents.
-
 struct nf7util_buffer {
   struct nf7util_malloc* malloc;
 

util/log.h

@@ -1,4 +1,7 @@
 // No copyright
+//
+// functions macros for logging
+//
 #pragma once
 
 #include <assert.h>

util/malloc.h

@@ -1,4 +1,9 @@
 // No copyright
+//
+// nf7util_malloc is a general purpose memory allocator
+// The current implementation is just a wrapper of malloc/free.
+// All methods are thread-safe.
+//
 #pragma once
 
 #include <assert.h>
@@ -7,9 +12,6 @@
 #include <stdlib.h>
 
 
-// ---- General Purpose Memory Allocator
-// The current implementation is just a wrap of malloc/free.
-// All methods are thread-safe.
 struct nf7util_malloc { atomic_uint_least64_t count; };
 
 static inline void* nf7util_malloc_alloc(struct nf7util_malloc* this, uint64_t n) {

util/refcnt.h

@@ -1,4 +1,26 @@
 // No copyright
+//
+// Refcnt util is a template macro of reference counting logic.
+//
+// HOW TO USE
+//   1. Define your struct whose instance is managed by reference couting.
+//      The struct must have an integer field named `refcnt`
+//
+//   2. Expand `NF7UTIL_REFCNT_DECL` in your header to declare ref/unref
+//      functions.
+//        - ATTR parameter is a space-separated list of attributes for them
+//        - T is a name of struct without `struct` keyword
+//        - e.g.) NF7UTIL_REFCNT_DECL(, mystruct);
+//
+//   3. Expand `NF7UTIL_REFCNT_IMPL` in your source to define the functions.
+//      DELETER parameter is a code block executed at all ownership is released.
+//        - A variable `T* this;` is available in the DELETER
+//        - e.g.) NF7UTIL_REFCNT_IMPL(, mystruct, {free(this);});
+//
+//   If you want functions inline, NF7UTIL_REFCNT_DECL is unnecessary, and just
+//   expand `NF7UTIL_REFCNT_IMPL` in your header like this:
+//     - e.g.) NF7UTIL_REFCNT_IMPL(static inline, mystruct, {free(this);})
+//
 #pragma once
 
 #include <assert.h>

util/signal.h

@@ -1,4 +1,11 @@
 // No copyright
+//
+// nf7util_signal is an emitter, and nf7util_signal_recv is its receiver.
+// When nf7util_signal emits, all of corresponding nf7util_signal_recv receive
+// and call their callbacks.
+//
+// This is useful to implement an observer pattern.
+//
 #pragma once
 
 #include "util/array.h"
@@ -24,7 +31,8 @@ struct nf7util_signal_recv {
 };
 
 
-static inline void nf7util_signal_init(struct nf7util_signal* this, struct nf7util_malloc* malloc) {
+static inline void nf7util_signal_init(
+    struct nf7util_signal* this, struct nf7util_malloc* malloc) {
   assert(nullptr != this);
   nf7util_signal_recvs_init(&this->recvs, malloc);
 }
@@ -47,7 +55,7 @@ static inline void nf7util_signal_emit(struct nf7util_signal* this) {
   this->emitting = false;
 
   // remove nullptr in recvs because a removed receiver replaces their pointer
-  // to nullptr in `recvs` while `this->emitting` is true
+  // in 'recvs' to nullptr while `this->emitting` is true
   uint64_t lead_index   = 0;
   uint64_t follow_index = 0;
   for (; lead_index < recvs->n; ++lead_index) {
@@ -71,7 +79,7 @@ static inline void nf7util_signal_recv_unset(struct nf7util_signal_recv* this) {
   if (!signal->emitting) {
     nf7util_signal_recvs_find_and_remove(&signal->recvs, this);
   } else {
-    // replace myself to nullptr in `signal->recvs`
+    // replace myself `signal->recvs` to nullptr in
     // because the array is being iterated while `signal->emitting` is true
     uint64_t index;
     if (nf7util_signal_recvs_find(&signal->recvs, &index, this)) {