--- libecb/ecb.pod	2011/05/27 00:04:05	1.19
+++ libecb/ecb.pod	2011/06/01 00:57:14	1.26
@@ -17,8 +17,9 @@
 it provides a number of other lowlevel C utilities, such as endianness
 detection, byte swapping or bit rotations.
 
-Or in other words, things that should be built-in into any standard C
-system, but aren't.
+Or in other words, things that should be built into any standard C system,
+but aren't, implemented as efficient as possible with GCC, and still
+correct with other compilers.
 
 More might come.
 
@@ -57,7 +58,21 @@
 
 =head2 GCC ATTRIBUTES
 
-blabla where to put, what others
+A major part of libecb deals with GCC attributes. These are additional
+attributes that you can assign to functions, variables and sometimes even
+types - much like C<const> or C<volatile> in C.
+
+While GCC allows declarations to show up in many surprising places,
+but not in many expected places, the safest way is to put attribute
+declarations before the whole declaration:
+
+   ecb_const int mysqrt (int a);
+   ecb_unused int i;
+
+For variables, it is often nicer to put the attribute after the name, and
+avoid multiple declarations using commas:
+
+   int i ecb_unused;
 
 =over 4
 
@@ -374,13 +389,15 @@
 (most-significant byte first) or little endian (least-significant byte
 first) respectively.
 
+On systems that are neither, their return values are unspecified.
+
 =item int ecb_ctz32 (uint32_t x)
 
 Returns the index of the least significant bit set in C<x> (or
-equivalently the number of bits set to 0 before the least significant
-bit set), starting from 0. If C<x> is 0 the result is undefined. A
-common use case is to compute the integer binary logarithm, i.e.,
-floor(log2(n)). For example:
+equivalently the number of bits set to 0 before the least significant bit
+set), starting from 0. If C<x> is 0 the result is undefined. A common use
+case is to compute the integer binary logarithm, i.e.,  C<floor (log2
+(n))>. For example:
 
   ecb_ctz32 (3) = 0
   ecb_ctz32 (6) = 1
@@ -396,16 +413,19 @@
 
 =item uint32_t ecb_bswap32 (uint32_t x)
 
-These two functions return the value of the 16-bit (32-bit) variable
-C<x> after reversing the order of bytes.
+These two functions return the value of the 16-bit (32-bit) value C<x>
+after reversing the order of bytes (0x11223344 becomes 0x44332211).
 
 =item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
 
 =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
 
-These two functions return the value of C<x> after shifting all the bits
+These two functions return the value of C<x> after rotating all the bits
 by C<count> positions to the right or left respectively.
 
+Current GCC versions understand these functions and usually compile them
+to "optimal" code (e.g. a single C<roll> on x86).
+
 =back
 
 =head2 ARITHMETIC
@@ -414,13 +434,29 @@
 
 =item x = ecb_mod (m, n)
 
-Returns the positive remainder of the modulo operation between C<m> and
-C<n>. Unlike the C modulo operator C<%>, this function ensures that the
-return value is always positive).
+Returns C<m> modulo C<n>, which is the same as the positive remainder
+of the division operation between C<m> and C<n>, using floored
+division. Unlike the C remainder operator C<%>, this function ensures that
+the return value is always positive and that the two numbers I<m> and
+I<m' = m + i * n> result in the same value modulo I<n> - in other words,
+C<ecb_mod> implements the mathematical modulo operation, which is missing
+in the language.
 
-C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be
+C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
 negatable, that is, both C<m> and C<-m> must be representable in its
-type.
+type (this typically includes the minimum signed integer value, the same
+limitation as for C</> and C<%> in C).
+
+Current GCC versions compile this into an efficient branchless sequence on
+many systems.
+
+For example, when you want to rotate forward through the members of an
+array for increasing C<m> (which might be negative), then you should use
+C<ecb_mod>, as the C<%> operator might give either negative results, or
+change direction for negative values:
+
+   for (m = -100; m <= 100; ++m)
+     int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
 
 =back
 
@@ -428,7 +464,7 @@
 
 =over 4
 
-=item element_count = ecb_array_length (name) [MACRO]
+=item element_count = ecb_array_length (name)
 
 Returns the number of elements in the array C<name>. For example: