X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=libsigrok.h;h=49d5aa8135722f897e759f9daa7c45d857b6e7ae;hb=7dc55d930f87433fb35ebf6f18f767eddb7e8a17;hp=fd09492ee0d8ccf9c4970a1ed1cd758a2dc85da3;hpb=393fb9cb18c5746d8567c9cf74b872804043345a;p=libsigrok.git

diff --git a/libsigrok.h b/libsigrok.h
index fd09492e..49d5aa81 100644
--- a/libsigrok.h
+++ b/libsigrok.h
@@ -34,6 +34,16 @@ extern "C" {
  * @file
  *
  * The public libsigrok header file to be used by frontends.
+ *
+ * This is the only file that libsigrok users (frontends) are supposed to
+ * use and #include. There are other header files which get installed with
+ * libsigrok, but those are not meant to be used directly by frontends.
+ *
+ * The correct way to get/use the libsigrok API functions is:
+ *
+ * @code{.c}
+ *   #include <libsigrok/libsigrok.h>
+ * @endcode
  */
 
 /*
@@ -161,7 +171,7 @@ enum {
 	SR_MQ_CONDUCTANCE,
 	/** Electrical power, usually in W, or dBm. */
 	SR_MQ_POWER,
-	/** Gain (e.g. a transistor's gain, or hFE). */
+	/** Gain (a transistor's gain, or hFE, for example). */
 	SR_MQ_GAIN,
 };
 
@@ -205,7 +215,7 @@ enum {
 	SR_MQFLAG_RMS = 0x04,
 	/** Value is voltage drop across a diode, or NAN. */
 	SR_MQFLAG_DIODE = 0x08,
-	/** Device is in "hold" mode, i.e. repeating the last measurement. */
+	/** Device is in "hold" mode (repeating the last measurement). */
 	SR_MQFLAG_HOLD = 0x10,
 	/** Device is in "max" mode, only updating upon a new max value. */
 	SR_MQFLAG_MAX = 0x20,
@@ -246,7 +256,7 @@ struct sr_datafeed_meta_analog {
 
 struct sr_datafeed_analog {
 	int num_samples;
-	/** Measured quantity (e.g. voltage, current, temperature). */
+	/** Measured quantity (voltage, current, temperature, and so on). */
 	int mq;
 	/** Unit in which the MQ is measured. */
 	int unit;
@@ -337,8 +347,8 @@ struct sr_hwopt {
 
 /** Hardware driver options. */
 enum {
-	/** Used to terminate lists. Must be 0! */
-	SR_HWOPT_DUMMY = 0,
+	/** Used to terminate lists. */
+	SR_HWOPT_DUMMY = 0, /* Must be 0! */
 
 	/**
 	 * Some drivers cannot detect the exact model they're talking to
@@ -347,18 +357,23 @@ enum {
 	SR_HWOPT_MODEL,
 
 	/**
-	 * Specification on how to connect to a device. In combination
-	 * with SR_HWOPT_SERIALCOMM, this is a serial port in the form
-	 * which makes sense to the operating system (e.g., /dev/ttyS0).
+	 * Specification on how to connect to a device.
+	 *
+	 * In combination with SR_HWOPT_SERIALCOMM, this is a serial port in
+	 * the form which makes sense to the OS (e.g., /dev/ttyS0).
 	 * Otherwise this specifies a USB device, either in the form of
-	 * [bus].[address] (decimal, e.g. 1.65) or [vendorid].[productid]
+	 * @verbatim <bus>.<address> @endverbatim (decimal, e.g. 1.65) or
+	 * @verbatim <vendorid>.<productid> @endverbatim
 	 * (hexadecimal, e.g. 1d6b.0001).
 	 */
 	SR_HWOPT_CONN,
 
 	/**
 	 * Serial communication specification, in the form:
-	 *   [baudrate]/[databits][parity][stopbits], e.g. 9600/8n1
+	 *
+	 *   @verbatim <baudrate>/<databits><parity><stopbits> @endverbatim
+	 *
+	 * Example: 9600/8n1
 	 *
 	 * This is always an optional parameter, since a driver typically
 	 * knows the speed at which the device wants to communicate.
@@ -368,8 +383,8 @@ enum {
 
 /** Hardware device capabilities. */
 enum {
-	/** Used to terminate lists. Must be 0! */
-	SR_HWCAP_DUMMY = 0,
+	/** Used to terminate lists. */
+	SR_HWCAP_DUMMY = 0, /* Must be 0! */
 
 	/*--- Device classes ------------------------------------------------*/
 
@@ -447,25 +462,25 @@ enum {
 	/*--- Acquisition modes ---------------------------------------------*/
 
 	/**
-	 * The device supports setting a sample time limit, i.e. how long the
-	 * sample acquisition should run (in ms).
+	 * The device supports setting a sample time limit (how long
+	 * the sample acquisition should run, in ms).
 	 */
 	SR_HWCAP_LIMIT_MSEC,
 
 	/**
-	 * The device supports setting a sample number limit, i.e. how many
-	 * samples should be acquired.
+	 * The device supports setting a sample number limit (how many
+	 * samples should be acquired).
 	 */
 	SR_HWCAP_LIMIT_SAMPLES,
 
 	/**
-	 * The device supports setting a frame limit, i.e. how many
-	 * frames should be acquired.
+	 * The device supports setting a frame limit (how many
+	 * frames should be acquired).
 	 */
 	SR_HWCAP_LIMIT_FRAMES,
 
 	/**
-	 * The device supports continuous sampling, i.e. neither a time limit
+	 * The device supports continuous sampling. Neither a time limit
 	 * nor a sample number limit has to be supplied, it will just acquire
 	 * samples continuously, until explicitly stopped by a certain command.
 	 */