Improve header documentation

15 files changed, 15 insertions, 14 deletions

diff --git a/src/backend.h b/src/backend.h
index f48287c..fe2fdf3 100644
--- a/src/backend.h
+++ b/src/backend.h
@@ -9,9 +9,8 @@
 
 #include <stdint.h>
 
-JALV_BEGIN_DECLS
-
 // Interface that must be implemented by audio/MIDI backends
+JALV_BEGIN_DECLS
 
 /// Initialize the audio and MIDI systems
 JalvBackend*
diff --git a/src/comm.h b/src/comm.h
index bd87e13..642a534 100644
--- a/src/comm.h
+++ b/src/comm.h
@@ -14,9 +14,8 @@
 
 #include <stdint.h>
 
-JALV_BEGIN_DECLS
-
 // Communication between the audio and main threads via rings
+JALV_BEGIN_DECLS
 
 /// Type of an internal message in a communication ring
 typedef enum {
diff --git a/src/control.h b/src/control.h
index beafa47..102fdad 100644
--- a/src/control.h
+++ b/src/control.h
@@ -15,10 +15,9 @@
 #include <stddef.h>
 #include <stdint.h>
 
+// Support for plugin controls (control port or event-based)
 JALV_BEGIN_DECLS
 
-// Plugin control utilities
-
 /// Type of plugin control
 typedef enum {
   PORT,    ///< Control port
diff --git a/src/frontend.h b/src/frontend.h
index 922707e..f95e64b 100644
--- a/src/frontend.h
+++ b/src/frontend.h
@@ -12,9 +12,8 @@
 
 #include <stdbool.h>
 
-JALV_BEGIN_DECLS
-
 // Interface that must be implemented by UIs
+JALV_BEGIN_DECLS
 
 /// Command-line arguments passed to an executable
 typedef struct {
diff --git a/src/jalv_internal.h b/src/jalv_internal.h
index 62cb873..dadd368 100644
--- a/src/jalv_internal.h
+++ b/src/jalv_internal.h
@@ -39,6 +39,7 @@
 #include <stdint.h>
 #include <stdio.h>
 
+// "Shared" internal application declarations
 JALV_BEGIN_DECLS
 
 /// LV2 features and associated data to be passed to plugins
diff --git a/src/log.h b/src/log.h
index d748a29..993ce36 100644
--- a/src/log.h
+++ b/src/log.h
@@ -21,9 +21,8 @@
 #  define JALV_LOG_FUNC(fmt, arg1)
 #endif
 
-JALV_BEGIN_DECLS
-
 // String and log utilities
+JALV_BEGIN_DECLS
 
 typedef enum {
   JALV_LOG_ERR     = 3,
diff --git a/src/nodes.h b/src/nodes.h
index d9b4a97..61deedc 100644
--- a/src/nodes.h
+++ b/src/nodes.h
@@ -8,6 +8,7 @@
 
 #include "lilv/lilv.h"
 
+// Cached lilv nodes
 JALV_BEGIN_DECLS
 
 typedef struct {
diff --git a/src/options.h b/src/options.h
index 3060eb3..1373e95 100644
--- a/src/options.h
+++ b/src/options.h
@@ -8,6 +8,7 @@
 
 #include <stdint.h>
 
+// Program options
 JALV_BEGIN_DECLS
 
 typedef struct {
diff --git a/src/port.h b/src/port.h
index 89185b1..e860a27 100644
--- a/src/port.h
+++ b/src/port.h
@@ -13,6 +13,7 @@
 #include <stddef.h>
 #include <stdint.h>
 
+// Application port state
 JALV_BEGIN_DECLS
 
 typedef struct {
diff --git a/src/process.h b/src/process.h
index da7470b..3dba625 100644
--- a/src/process.h
+++ b/src/process.h
@@ -10,9 +10,8 @@
 #include <stdbool.h>
 #include <stdint.h>
 
-JALV_BEGIN_DECLS
-
 // Code and data used in the realtime process thread
+JALV_BEGIN_DECLS
 
 /**
    Run the plugin for a block of frames.
diff --git a/src/state.h b/src/state.h
index dfc3174..172b415 100644
--- a/src/state.h
+++ b/src/state.h
@@ -13,9 +13,8 @@
 #include "lv2/urid/urid.h"
 #include "serd/serd.h"
 
-JALV_BEGIN_DECLS
-
 // State and preset utilities
+JALV_BEGIN_DECLS
 
 typedef int (*PresetSink)(Jalv*           jalv,
                           const LilvNode* node,
diff --git a/src/string_utils.h b/src/string_utils.h
index 53f09fd..d99e10e 100644
--- a/src/string_utils.h
+++ b/src/string_utils.h
@@ -6,6 +6,7 @@
 
 #include "attributes.h"
 
+// String utilities
 JALV_BEGIN_DECLS
 
 /// Return a newly allocated copy of a string
diff --git a/src/types.h b/src/types.h
index dcb15c6..4f25301 100644
--- a/src/types.h
+++ b/src/types.h
@@ -6,6 +6,7 @@
 
 #include "attributes.h"
 
+// Basic internal type declarations
 JALV_BEGIN_DECLS
 
 /// Process thread running state
diff --git a/src/urids.h b/src/urids.h
index ee00d66..4cab740 100644
--- a/src/urids.h
+++ b/src/urids.h
@@ -9,6 +9,7 @@
 
 #include "lv2/urid/urid.h"
 
+// Cached LV2 URIDs
 JALV_BEGIN_DECLS
 
 typedef struct {
diff --git a/src/worker.h b/src/worker.h
index 09d35ca..a98bfc6 100644
--- a/src/worker.h
+++ b/src/worker.h
@@ -14,6 +14,7 @@
 #include <stdbool.h>
 #include <stdint.h>
 
+// Worker implementation
 JALV_BEGIN_DECLS
 
 /**