Doc: Described ff-binary.

diff --git a/ucw/doc/fastbuf.txt b/ucw/doc/fastbuf.txt
index 894d078053f759176d26df5d92d16450b8305df7..d94fffe90cf44cef4cf9f12024d7f7e1acbb8ba0 100644 (file)
--- a/ucw/doc/fastbuf.txt
+++ b/ucw/doc/fastbuf.txt
@@ -60,4 +60,4 @@ Invalid codes are replaced by `UNI_REPLACEMENT` when reading.
 ucw/ff-binary.h
 ---------------
 
-Reading and writing of binary values.
+!!ucw/ff-binary.h

diff --git a/ucw/ff-binary.h b/ucw/ff-binary.h
index edba770cfac02fe54fb42bf12a01e5d67657ab28..0e9144d54cc76bec12001afd449762f89de46a55 100644 (file)
--- a/ucw/ff-binary.h
+++ b/ucw/ff-binary.h
@@ -20,6 +20,32 @@
 #define FF_ENDIAN le
 #endif
 
+/***
+ *
+ * We define several functions to read or write binary integer values.
+ *
+ * The name patterns for such routines are:
+ *
+ * - `TYPE bget \#\# NAME \#\# ENDIAN(struct fastbuf *f);`
+ * - `void bput \#\# NAME \#\# ENDIAN(struct fastbuf *f, TYPE value);`
+ *
+ * where `NAME` together with `TYPE` can be:
+ *
+ * - `w` for 16-bit unsigned integers stored in sequences of 2 bytes, the `TYPE` is int
+ * - `l` for 32-bit unsigned integers stored in sequences of 4 bytes, the `TYPE` is uns
+ * - `5` for 40-bit unsigned integers stored in sequences of 5 bytes, the `TYPE` is u64
+ * - `q` for 64-bit unsigned integers stored in sequences of 8 bytes, the `TYPE` is u64
+ *
+ * and supported `ENDIAN` suffixes are:
+ *
+ * - empty for the default order of bytes (defined by CPU)
+ * - `_le` for little-endian
+ * - `_be` for big-endian
+ *
+ * If we fail to read enough bytes because the EOF, the reading function returns `(TYPE)-1`.
+ *
+ ***/
+
 #define GET_FUNC(type, name, bits, endian)                     \
   type bget##name##_##endian##_slow(struct fastbuf *f);                \
   static inline type bget##name##_##endian(struct fastbuf *f)  \