From: Matthias Heidbrink <redacted>
Date: Wed, 5 Feb 2014 13:32:21 +0000 (+0100)
Subject: Update/extend some Doxygen comments.
X-Git-Tag: libsigrok-0.3.0~147
X-Git-Url: http://sigrok.org/gitweb/?p=libsigrok.git;a=commitdiff_plain;h=813aab691b255580d3247b9fec7ab3f7b4fc8a18

Update/extend some Doxygen comments.
---

diff --git a/libsigrok.h b/libsigrok.h
index cda125c5..810276c1 100644
--- a/libsigrok.h
+++ b/libsigrok.h
@@ -953,33 +953,55 @@ enum {
 	SR_ST_STOPPING,
 };
 
-/** Device driver data */
+/** Device driver data. See also http://sigrok.org/wiki/Hardware_driver_API . */
 struct sr_dev_driver {
 	/* Driver-specific */
-	/** Driver name */
+	/** Driver name. Lowercase a-z, 0-9 and dashes (-) only. */
 	char *name;
-	/** Long name, e.g. device name. */
+	/** Long name. Verbose driver name shown to user. */
 	char *longname;
 	/** API version (currently 1).	*/
 	int api_version;
-	/** Init driver */
+	/** Called when driver is loaded, e.g. program startup. */
 	int (*init) (struct sr_context *sr_ctx);
-	/** Free driver */
+	/** Called before driver is unloaded.
+	 *  Driver must free all resouces held by it. */
 	int (*cleanup) (void);
-	/** Scan for devices */
+	/** Scan for devices. Driver should do all initialisation required.
+	 *  Can be called several times, e.g. with different port options.
+	 *  \retval NULL Error or no devices found.
+	 *  \retval other GSList of a struct sr_dev_inst for each device.
+	 *                Must be freed by caller!
+	 */
 	GSList *(*scan) (GSList *options);
-	/** Get device list */
+	/** Get list of device instances the driver knows about.
+	 *  \returns NULL or GSList of a struct sr_dev_inst for each device.
+	 *           Must not be freed by caller!
+	 */
 	GSList *(*dev_list) (void);
+	/** Clear list of devices the driver knows about. */
 	int (*dev_clear) (void);
+	/** Query value of a configuration key in driver or given device instance.
+	 *  @see sr_config_get().
+	 */
 	int (*config_get) (int id, GVariant **data,
 			const struct sr_dev_inst *sdi,
 			const struct sr_probe_group *probe_group);
+	/** Set value of a configuration key in driver or a given device instance.
+	 *  @see sr_config_set(). */
 	int (*config_set) (int id, GVariant *data,
 			const struct sr_dev_inst *sdi,
 			const struct sr_probe_group *probe_group);
+	/** Probe status change.
+	 *  @see sr_dev_probe_enable(), sr_dev_trigger_set(). */
 	int (*config_probe_set) (const struct sr_dev_inst *sdi,
 			struct sr_probe *probe, unsigned int changes);
+	/** Apply configuration settings to the device hardware.
+	 *  @see sr_config_commit().*/
 	int (*config_commit) (const struct sr_dev_inst *sdi);
+	/** List all possible values for a configuration key in a device instance.
+	 *  @see sr_config_list().
+	 */
 	int (*config_list) (int info_id, GVariant **data,
 			const struct sr_dev_inst *sdi,
 			const struct sr_probe_group *probe_group);
@@ -989,15 +1011,15 @@ struct sr_dev_driver {
 	int (*dev_open) (struct sr_dev_inst *sdi);
 	/** Close device */
 	int (*dev_close) (struct sr_dev_inst *sdi);
-	/** Start data aquisition. */
+	/** Begin data aquisition on the specified device. */
 	int (*dev_acquisition_start) (const struct sr_dev_inst *sdi,
 			void *cb_data);
-	/** Stop data aquisition. */
+	/** End data aquisition on the specified device. */
 	int (*dev_acquisition_stop) (struct sr_dev_inst *sdi,
 			void *cb_data);
 
 	/* Dynamic */
-	/** Device driver private data */
+	/** Device driver private data. Initialized by init(). */
 	void *priv;
 };
 
diff --git a/std.c b/std.c
index 30b8d1d4..1a65b039 100644
--- a/std.c
+++ b/std.c
@@ -110,7 +110,7 @@ SR_PRIV int std_session_send_df_header(const struct sr_dev_inst *sdi,
 
 #ifdef HAVE_LIBSERIALPORT
 
-/*
+/**
  * Standard serial driver dev_open() helper.
  *
  * This function can be used to implement the dev_open() driver API
@@ -136,7 +136,7 @@ SR_PRIV int std_serial_dev_open(struct sr_dev_inst *sdi)
 	return SR_OK;
 }
 
-/*
+/**
  * Standard serial driver dev_close() helper.
  *
  * This function can be used to implement the dev_close() driver API
@@ -160,7 +160,7 @@ SR_PRIV int std_serial_dev_close(struct sr_dev_inst *sdi)
 	return SR_OK;
 }
 
-/*
+/**
  * Standard sr_session_stop() API helper.
  *
  * This function can be used to simplify most (serial port based) driver's
@@ -173,7 +173,7 @@ SR_PRIV int std_serial_dev_close(struct sr_dev_inst *sdi)
  *               	  Must not be NULL.
  * @param serial The serial device instance (struct serial_dev_inst *).
  *               Must not be NULL.
- * @param prefix A driver-specific prefix string used for log messages.
+ * @param[in] prefix A driver-specific prefix string used for log messages.
  *               Must not be NULL. An empty string is allowed.
  *
  * @retval SR_OK Success.
@@ -224,9 +224,11 @@ SR_PRIV int std_serial_dev_acquisition_stop(struct sr_dev_inst *sdi,
 
 #endif
 
-/*
+/**
  * Standard driver dev_clear() helper.
  *
+ * Clear driver, this means, close all instances.
+ *
  * This function can be used to implement the dev_clear() driver API
  * callback. dev_close() is called before every sr_dev_inst is cleared.
  *
@@ -287,4 +289,3 @@ SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver,
 
 	return ret;
 }
-