sr: more API cleanup and documentation

diff --git a/device.c b/device.c
index 886a5040eae277adde6ae64c2817cd818976d9d3..e3543d5345701cfad7f16a138bdf5c35bd13125e 100644 (file)
--- a/device.c
+++ b/device.c
@@ -75,7 +75,7 @@ SR_API int sr_device_scan(void)
        for (l = plugins; l; l = l->next) {
                plugin = l->data;
                /* TODO: Handle 'plugin' being NULL. */
-               sr_init_hwplugins(plugin);
+               sr_init_hwplugin(plugin);
        }
 
        return SR_OK;

diff --git a/hwplugin.c b/hwplugin.c
index 06cd96905397c4c42d9ca2f97947a4fa8d74463c..dfee3814bd32e4ce6533db4fc052b04fa5d42b71 100644 (file)
--- a/hwplugin.c
+++ b/hwplugin.c
@@ -100,12 +100,31 @@ SR_PRIV int load_hwplugins(void)
        return SR_OK;
 }
 
+/**
+ * Returns the list of loaded hardware plugins.
+ *
+ * The list of plugins is initialized from sr_init(), and can only be reset
+ * by calling sr_exit().
+ *
+ * @return A GSList of pointers to loaded plugins.
+ */
 SR_API GSList *sr_list_hwplugins(void)
 {
+
        return plugins;
 }
 
-SR_API int sr_init_hwplugins(struct sr_device_plugin *plugin)
+/**
+ * Initialize a hardware plugin.
+ *
+ * The specified plugin is initialized, and all devices discovered by the
+ * plugin are instantiated.
+ *
+ * @param plugin The plugin to initialize.
+ *
+ * @return The number of devices found and instantiated by the plugin.
+ */
+SR_API int sr_init_hwplugin(struct sr_device_plugin *plugin)
 {
        int num_devices, num_probes, i, j;
        int num_initialized_devices = 0;
@@ -244,7 +263,16 @@ SR_PRIV void sr_serial_device_instance_free(
        g_free(serial->port);
 }
 
-SR_API int sr_find_hwcap(int *capabilities, int hwcap)
+/**
+ * Find out if a list of hardware plugin capabilities has a specific cap.
+ *
+ * @param capabilities A NULL-terminated integer array of capabilities, as
+ * returned by a plugin's get_capabilities() function.
+ * @param hwcap The capability to find in the list.
+ *
+ * @return Returns TRUE if found, FALSE otherwise.
+ */
+SR_API gboolean sr_has_hwcap(int *capabilities, int hwcap)
 {
        int i;
 
@@ -256,6 +284,14 @@ SR_API int sr_find_hwcap(int *capabilities, int hwcap)
        return FALSE;
 }
 
+/**
+ * Find a hardware plugin capability option parameter structure.
+ *
+ * @param hwcap The capability to find
+ *
+ * @return Returns a struct with information about the parameter, or NULL
+ * if not found.
+ */
 SR_API struct sr_hwcap_option *sr_find_hwcap_option(int hwcap)
 {
        int i;

diff --git a/session.c b/session.c
index b33baa5c57f32a990d62dba28ce3e0816dc87d2d..15a72989e5bf4c1993433a24e371d5d174a14340 100644 (file)
--- a/session.c
+++ b/session.c
@@ -47,9 +47,6 @@ static int source_timeout = -1;
 /**
  * Create a new session.
  *
- * TODO.
- *
- * TODO: Should return int?
  * TODO: Should it use the file-global "session" variable or take an argument?
  *       The same question applies to all the other session functions.
  *
@@ -160,8 +157,6 @@ SR_API int sr_session_device_add(struct sr_device *device)
 /**
  * Clear all datafeed callbacks in the current session.
  *
- * TODO.
- *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
 SR_API int sr_session_datafeed_callback_clear(void)
@@ -180,7 +175,8 @@ SR_API int sr_session_datafeed_callback_clear(void)
 /**
  * Add a datafeed callback to the current session.
  *
- * @param callback TODO.
+ * @param callback Function to call when a chunk of data is received.
+ *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
 SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback callback)
@@ -251,7 +247,7 @@ static int sr_session_run_poll(void)
 /**
  * Start a session.
  *
- * There can only be one session at a time. TODO
+ * There can only be one session at a time.
  *
  * @return SR_OK upon success, SR_ERR upon errors.
  */
@@ -335,7 +331,8 @@ SR_API int sr_session_run(void)
 /**
  * Halt the current session.
  *
- * TODO.
+ * This requests the current session be stopped as soon as possible, for example
+ * on receiving an SR_DF_END packet.
  *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
@@ -355,7 +352,8 @@ SR_API int sr_session_halt(void)
 /**
  * Stop the current session.
  *
- * TODO: Difference to halt?
+ * The current session is stopped immediately, with all acquisition sessions
+ * being stopped and hardware plugins cleaned up.
  *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
@@ -387,7 +385,7 @@ SR_API int sr_session_stop(void)
 }
 
 /**
- * @brief debug helper
+ * Debug helper.
  *
  * @param packet The packet to show debugging information for.
  *
@@ -419,13 +417,15 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
 }
 
 /**
- * TODO.
+ * Send a packet to whatever is listening on the datafeed bus.
+ *
+ * Hardware drivers use this to send a data packet to the frontend.
  *
  * @param device TODO.
  * @param packet TODO.
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
  */
-SR_API int sr_session_bus(struct sr_device *device,
+SR_PRIV int sr_session_bus(struct sr_device *device,
                          struct sr_datafeed_packet *packet)
 {
        GSList *l;
@@ -446,10 +446,6 @@ SR_API int sr_session_bus(struct sr_device *device,
                return SR_ERR_ARG;
        }
 
-       /*
-        * TODO: Send packet through PD pipe, and send the output of that to
-        * the callbacks as well.
-        */
        for (l = session->datafeed_callbacks; l; l = l->next) {
                if (sr_log_loglevel_get() >= SR_LOG_DBG)
                        datafeed_dump(packet);

diff --git a/sigrok-internal.h b/sigrok-internal.h
index f115c530ba28c3f5aea011ab98d74c83377665d5..f6a35624a645883d654c9bb07519afb0d7a7fb21 100644 (file)
--- a/sigrok-internal.h
+++ b/sigrok-internal.h
@@ -80,6 +80,11 @@ SR_PRIV int sr_err(const char *format, ...);
 SR_PRIV int load_hwplugins(void);
 SR_PRIV void sr_cleanup_hwplugins(void);
 
+/*--- session.c -------------------------------------------------------------*/
+
+SR_PRIV int sr_session_bus(struct sr_device *device,
+                         struct sr_datafeed_packet *packet);
+
 /* Generic device instances */
 SR_PRIV struct sr_device_instance *sr_device_instance_new(int index,
        int status, const char *vendor, const char *model, const char *version);

diff --git a/sigrok-proto.h b/sigrok-proto.h
index 209ff963010987e862bf47a77cd2c81a54a938f7..0efdaeec71b84bc1300f87f6dba2154bcfe8bfb1 100644 (file)
--- a/sigrok-proto.h
+++ b/sigrok-proto.h
@@ -73,8 +73,8 @@ SR_API int sr_filter_probes(int in_unitsize, int out_unitsize,
 /*--- hwplugin.c ------------------------------------------------------------*/
 
 SR_API GSList *sr_list_hwplugins(void);
-SR_API int sr_init_hwplugins(struct sr_device_plugin *plugin);
-SR_API int sr_find_hwcap(int *capabilities, int hwcap);
+SR_API int sr_init_hwplugin(struct sr_device_plugin *plugin);
+SR_API gboolean sr_has_hwcap(int *capabilities, int hwcap);
 SR_API struct sr_hwcap_option *sr_find_hwcap_option(int hwcap);
 
 /*--- session.c -------------------------------------------------------------*/
@@ -98,8 +98,6 @@ SR_API int sr_session_start(void);
 SR_API int sr_session_run(void);
 SR_API int sr_session_halt(void);
 SR_API int sr_session_stop(void);
-SR_API int sr_session_bus(struct sr_device *device,
-                         struct sr_datafeed_packet *packet);
 SR_API int sr_session_save(const char *filename);
 SR_API int sr_session_source_add(int fd, int events, int timeout,
                sr_receive_data_callback callback, void *user_data);