From 50cffcfe2c479fac9d815cfb28c19e1854070d56 Mon Sep 17 00:00:00 2001
From: Paul Sokolovsky <pfalcon@users.sourceforge.net>
Date: Thu, 26 Oct 2017 23:11:09 +0300
Subject: [PATCH] docs/uctypes: Tweak descriptor reference to hopefully be
 easier to follow.

Put offset first in OR expressions, and use "offset" var instead of
hardcoded numbers. Hopefully, this will make it more self-describing
and show patterns better.
---
 docs/library/uctypes.rst | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/docs/library/uctypes.rst b/docs/library/uctypes.rst
index 164e0eb9d7..c938d74a8e 100644
--- a/docs/library/uctypes.rst
+++ b/docs/library/uctypes.rst
@@ -29,16 +29,16 @@ Following are encoding examples for various field types:
 
 * Scalar types::
 
-    "field_name": uctypes.UINT32 | 0
+    "field_name": offset | uctypes.UINT32
 
   in other words, value is scalar type identifier ORed with field offset
   (in bytes) from the start of the structure.
 
 * Recursive structures::
 
-    "sub": (2, {
-        "b0": uctypes.UINT8 | 0,
-        "b1": uctypes.UINT8 | 1,
+    "sub": (offset, {
+        "b0": 0 | uctypes.UINT8,
+        "b1": 1 | uctypes.UINT8,
     })
 
   i.e. value is a 2-tuple, first element of which is offset, and second is
@@ -47,7 +47,7 @@ Following are encoding examples for various field types:
 
 * Arrays of primitive types::
 
-      "arr": (uctypes.ARRAY | 0, uctypes.UINT8 | 2),
+      "arr": (offset | uctypes.ARRAY, size | uctypes.UINT8),
 
   i.e. value is a 2-tuple, first element of which is ARRAY flag ORed
   with offset, and second is scalar element type ORed number of elements
@@ -55,7 +55,7 @@ Following are encoding examples for various field types:
 
 * Arrays of aggregate types::
 
-    "arr2": (uctypes.ARRAY | 0, 2, {"b": uctypes.UINT8 | 0}),
+    "arr2": (offset | uctypes.ARRAY, size, {"b": 0 | uctypes.UINT8}),
 
   i.e. value is a 3-tuple, first element of which is ARRAY flag ORed
   with offset, second is a number of elements in array, and third is
@@ -63,21 +63,21 @@ Following are encoding examples for various field types:
 
 * Pointer to a primitive type::
 
-    "ptr": (uctypes.PTR | 0, uctypes.UINT8),
+    "ptr": (offset | uctypes.PTR, uctypes.UINT8),
 
   i.e. value is a 2-tuple, first element of which is PTR flag ORed
   with offset, and second is scalar element type.
 
 * Pointer to an aggregate type::
 
-    "ptr2": (uctypes.PTR | 0, {"b": uctypes.UINT8 | 0}),
+    "ptr2": (offset | uctypes.PTR, {"b": 0 | uctypes.UINT8}),
 
   i.e. value is a 2-tuple, first element of which is PTR flag ORed
   with offset, second is descriptor of type pointed to.
 
 * Bitfields::
 
-    "bitf0": uctypes.BFUINT16 | 0 | 0 << uctypes.BF_POS | 8 << uctypes.BF_LEN,
+    "bitf0": offset | uctypes.BFUINT16 | lsbit << uctypes.BF_POS | bitsize << uctypes.BF_LEN,
 
   i.e. value is type of scalar value containing given bitfield (typenames are
   similar to scalar types, but prefixes with "BF"), ORed with offset for
@@ -91,9 +91,10 @@ Following are encoding examples for various field types:
   In the example above, first a UINT16 value will be extracted at offset 0
   (this detail may be important when accessing hardware registers, where
   particular access size and alignment are required), and then bitfield
-  whose rightmost bit is least-significant bit of this UINT16, and length
-  is 8 bits, will be extracted - effectively, this will access
-  least-significant byte of UINT16.
+  whose rightmost bit is *lsbit* bit of this UINT16, and length
+  is *bitsize* bits, will be extracted. For example, if *lsbit* is 0 and
+  *bitsize* is 8, then effectively it will access least-significant byte
+  of UINT16.
 
   Note that bitfield operations are independent of target byte endianness,
   in particular, example above will access least-significant byte of UINT16