Add brief comments for undocumented "public" functions

4 files changed, 24 insertions, 1 deletions

diff --git a/src/control.h b/src/control.h
index e0966f5..46bc158 100644
--- a/src/control.h
+++ b/src/control.h
@@ -88,9 +88,11 @@ new_property_control(LilvWorld*       world,
                      LV2_URID_Map*    map,
                      LV2_Atom_Forge*  forge);
 
+/// Add a control to the given controls set, reallocating as necessary
 void
 add_control(Controls* controls, ControlID* control);
 
+/// Return a pointer to the control for the given property, or null
 ControlID*
 get_property_control(const Controls* controls, LV2_URID property);
 
diff --git a/src/jalv.c b/src/jalv.c
index 6c131bc..19fd718 100644
--- a/src/jalv.c
+++ b/src/jalv.c
@@ -253,7 +253,6 @@ jalv_create_ports(Jalv* jalv)
   free(default_values);
 }
 
-/// Allocate port buffers (only necessary for MIDI)
 void
 jalv_allocate_port_buffers(Jalv* jalv)
 {
diff --git a/src/jalv_internal.h b/src/jalv_internal.h
index ee2a11e..1eea246 100644
--- a/src/jalv_internal.h
+++ b/src/jalv_internal.h
@@ -41,6 +41,7 @@
 
 JALV_BEGIN_DECLS
 
+/// LV2 features and associated data to be passed to plugins
 typedef struct {
   LV2_Feature                map_feature;
   LV2_Feature                unmap_feature;
@@ -60,6 +61,7 @@ typedef struct {
   LV2_Extension_Data_Feature ext_data;
 } JalvFeatures;
 
+/// Internal application state
 struct JalvImpl {
   JalvOptions       opts;         ///< Command-line options
   JalvURIDs         urids;        ///< URIDs
@@ -118,18 +120,23 @@ struct JalvImpl {
   const LV2_Feature** feature_list;
 };
 
+/// Load the plugin and set up the application
 int
 jalv_open(Jalv* jalv, int* argc, char*** argv);
 
+/// Shut down the application (counterpart to jalv_open)
 int
 jalv_close(Jalv* jalv);
 
+/// Allocate appropriately-sized port buffers and connect the plugin to them
 void
 jalv_allocate_port_buffers(Jalv* jalv);
 
+/// Find a port by symbol
 struct Port*
 jalv_port_by_symbol(Jalv* jalv, const char* sym);
 
+/// Set a control to the given value
 void
 jalv_set_control(Jalv*            jalv,
                  const ControlID* control,
@@ -137,15 +144,19 @@ jalv_set_control(Jalv*            jalv,
                  LV2_URID         type,
                  const void*      body);
 
+/// Request and/or set initial control values to initialize the UI
 void
 jalv_init_ui(Jalv* jalv);
 
+/// Instantiate the UI instance using suil if available
 void
 jalv_ui_instantiate(Jalv* jalv, const char* native_ui_type, void* parent);
 
+/// Return true if the plugin UI isn't declared as non-resizable
 bool
 jalv_ui_is_resizable(Jalv* jalv);
 
+/// Called when a port event (control change or other message) is sent to the UI
 void
 jalv_ui_port_event(Jalv*       jalv,
                    uint32_t    port_index,
@@ -192,6 +203,7 @@ jalv_write_control(const Jalv* jalv,
                    uint32_t    port_index,
                    float       value);
 
+/// Dump an atom to stdout in a "developer-readable" format (Turtle)
 void
 jalv_dump_atom(Jalv*           jalv,
                FILE*           stream,
@@ -199,9 +211,11 @@ jalv_dump_atom(Jalv*           jalv,
                const LV2_Atom* atom,
                int             color);
 
+/// Run plugin instance for one buffer
 bool
 jalv_run(Jalv* jalv, uint32_t nframes);
 
+/// Periodically update user interface
 int
 jalv_update(Jalv* jalv);
 
diff --git a/src/log.h b/src/log.h
index 9528a3d..e4dd546 100644
--- a/src/log.h
+++ b/src/log.h
@@ -38,30 +38,38 @@ typedef struct {
   bool       tracing;
 } JalvLog;
 
+/// Print a control value to stderr, like "sym = 1.234"
 void
 jalv_print_control(const Jalv* jalv, const struct Port* port, float value);
 
+/// Return a newly allocated copy of a string
 char*
 jalv_strdup(const char* str);
 
+/// Return a newly allocated concatenation of two strings
 char*
 jalv_strjoin(const char* a, const char* b);
 
+/// Print a log message to stderr with a GCC-like prefix and color
 JALV_LOG_FUNC(2, 3)
 int
 jalv_log(JalvLogLevel level, const char* fmt, ...);
 
+/// LV2 log vprintf function
 JALV_LOG_FUNC(3, 0)
 int
 jalv_vprintf(LV2_Log_Handle handle, LV2_URID type, const char* fmt, va_list ap);
 
+/// LV2 log printf function
 JALV_LOG_FUNC(3, 4)
 int
 jalv_printf(LV2_Log_Handle handle, LV2_URID type, const char* fmt, ...);
 
+/// Write an ANSI escape sequence to set the foreground color
 bool
 jalv_ansi_start(FILE* stream, int color);
 
+/// Write an ANSI escape sequence to reset the foreground color
 void
 jalv_ansi_reset(FILE* stream);