X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=include%2Flibsigrok%2Flibsigrok.h;fp=include%2Flibsigrok%2Flibsigrok.h;h=58216c2cdcb525329b505a19c30938ab7f083009;hb=8e461052a6ba0ad356ca1ec6daa13e0829fdfd69;hp=5300fbe1951e5027a9e587c38b52e1df19590edb;hpb=e7c7aa119d49c9a8f25cb32858c74bfe5a4efb23;p=libsigrok.git

diff --git a/include/libsigrok/libsigrok.h b/include/libsigrok/libsigrok.h
index 5300fbe1..58216c2c 100644
--- a/include/libsigrok/libsigrok.h
+++ b/include/libsigrok/libsigrok.h
@@ -529,9 +529,22 @@ struct sr_analog_encoding {
 	gboolean is_float;
 	gboolean is_bigendian;
 	/**
-	 * Number of significant digits after the decimal point if positive,
-	 * or number of non-significant digits before the decimal point if
-	 * negative (refers to the value we actually read on the wire).
+	 * Number of significant digits after the decimal point, if positive.
+	 * When negative, exponent with reversed polarity that is necessary to
+	 * express the value with all digits without a decimal point.
+	 * Refers to the value we actually read on the wire.
+	 *
+	 * Examples:
+	 *
+	 * | Disp. value | Exp. notation       | Exp. not. normalized | digits |
+	 * |-------------|---------------------|----------------------|--------|
+	 * |  12.34 MOhm |  1.234 * 10^7   Ohm |    1234 * 10^4   Ohm |     -4 |
+	 * | 1.2345 MOhm | 1.2345 * 10^6   Ohm |   12345 * 10^2   Ohm |     -2 |
+	 * |  123.4 kOhm |  1.234 * 10^5   Ohm |    1234 * 10^2   Ohm |     -2 |
+	 * |   1234  Ohm |  1.234 * 10^3   Ohm |    1234 * 10^0   Ohm |      0 |
+	 * |  12.34  Ohm |  1.234 * 10^1   Ohm |    1234 * 10^-2  Ohm |      2 |
+	 * | 0.0123  Ohm |   1.23 * 10^-2  Ohm |     123 * 10^-4  Ohm |      4 |
+	 * |  1.234 pF   |  1.234 * 10^-12 F   |    1234 * 10^-15 F   |     15 |
 	 */
 	int8_t digits;
 	gboolean is_digits_decimal;
@@ -548,10 +561,22 @@ struct sr_analog_meaning {
 
 struct sr_analog_spec {
 	/**
-	 * Number of significant digits after the decimal point if positive,
-	 * or number of non-significant digits before the decimal point if
-	 * negative (refers to vendor specifications/datasheet or actual
-	 * device display).
+	 * Number of significant digits after the decimal point, if positive.
+	 * When negative, exponent with reversed polarity that is necessary to
+	 * express the value with all digits without a decimal point.
+	 * Refers to vendor specifications/datasheet or actual device display.
+	 *
+	 * Examples:
+	 *
+	 * | On the wire | Exp. notation       | Exp. not. normalized | spec_digits |
+	 * |-------------|---------------------|----------------------|-------------|
+	 * |  12.34 MOhm |  1.234 * 10^7   Ohm |    1234 * 10^4   Ohm |          -4 |
+	 * | 1.2345 MOhm | 1.2345 * 10^6   Ohm |   12345 * 10^2   Ohm |          -2 |
+	 * |  123.4 kOhm |  1.234 * 10^5   Ohm |    1234 * 10^2   Ohm |          -2 |
+	 * |   1234  Ohm |  1.234 * 10^3   Ohm |    1234 * 10^0   Ohm |           0 |
+	 * |  12.34  Ohm |  1.234 * 10^1   Ohm |    1234 * 10^-2  Ohm |           2 |
+	 * | 0.0123  Ohm |   1.23 * 10^-2  Ohm |     123 * 10^-4  Ohm |           4 |
+	 * |  1.234 pF   |  1.234 * 10^-12 F   |    1234 * 10^-15 F   |          15 |
 	 */
 	int8_t spec_digits;
 };