From: Frank Stettner <redacted>
Date: Fri, 27 Jan 2023 12:28:05 +0000 (+0100)
Subject: Reword and clarify the doc strings for digits in the analog payload
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=8e461052a6ba0ad356ca1ec6daa13e0829fdfd69;p=libsigrok.git

Reword and clarify the doc strings for digits in the analog payload

Clarifies the intended use of the properties sr_analog_encoding.digits and
sr_analog_spec.spec_digits used in the analog payload and also digits() in
the Analog class of the C++ bindings.

These properties hold the 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.
---

diff --git a/bindings/cxx/include/libsigrokcxx/libsigrokcxx.hpp b/bindings/cxx/include/libsigrokcxx/libsigrokcxx.hpp
index d090c379..3bebdd23 100644
--- a/bindings/cxx/include/libsigrokcxx/libsigrokcxx.hpp
+++ b/bindings/cxx/include/libsigrokcxx/libsigrokcxx.hpp
@@ -791,9 +791,22 @@ public:
 	/** Samples are stored in big-endian order. */
 	bool is_bigendian() const;
 	/**
-	 * 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:
+	 *
+	 * | On the wire | Exponential 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 |
 	 */
 	int digits() const;
 	/** TBD */
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;
 };