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 d090c37997525b8851f23f0772c80d355a165365..3bebdd234936c246b7a559ad3569ce509d79629a 100644 (file)
--- 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 5300fbe1951e5027a9e587c38b52e1df19590edb..58216c2cdcb525329b505a19c30938ab7f083009 100644 (file)
--- 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;
 };