From: Michal Vaner <vorner@ucw.cz>
Date: Sun, 3 Aug 2008 09:00:14 +0000 (+0200)
Subject: Libucw: Documentation of more fastbuf headers.
X-Git-Tag: holmes-import~352
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=358add5a78f8f8e2ba704dc1a877222e5620e838;p=libucw.git

Libucw: Documentation of more fastbuf headers.
---

diff --git a/ucw/doc/fastbuf.txt b/ucw/doc/fastbuf.txt
index 71e9dc07..754acd3e 100644
--- a/ucw/doc/fastbuf.txt
+++ b/ucw/doc/fastbuf.txt
@@ -12,3 +12,24 @@ ucw/fastbuf.h
 -------------
 
 !!ucw/fastbuf.h
+
+ucw/fb-socket.h
+---------------
+
+Fastbufs on network sockets with timeouts.
+
+!!ucw/fb-socket.h
+
+ucw/ff-unicode.h
+----------------
+
+Reading and writing of unicode characters.
+
+Invalid codes are replaced by +UNI_REPLACEMENT+ when reading.
+
+!!ucw/ff-unicode.h
+
+ucw/ff-binary.h
+---------------
+
+Reading and writing of binary values.
diff --git a/ucw/fb-socket.h b/ucw/fb-socket.h
index b8008604..c9f6806b 100644
--- a/ucw/fb-socket.h
+++ b/ucw/fb-socket.h
@@ -12,7 +12,7 @@
 
 #include "ucw/fastbuf.h"
 
-struct fbsock_params {
+struct fbsock_params {	/** Configuration of socket fastbuf. **/
   int fd;
   uns bufsize;
   uns timeout_ms;
@@ -20,12 +20,16 @@ struct fbsock_params {
   void *data;			// Passed to the err callback
 };
 
-enum fbsock_err_flags {
+enum fbsock_err_flags {	/** Description of a socket error **/
   FBSOCK_READ = 1,		// Happened during read
   FBSOCK_WRITE = 2,		// Happened during write
   FBSOCK_TIMEOUT = 4,		// The error is a timeout
 };
 
+/**
+ * Create a new socket fastbuf.
+ * All information is passed by @par.
+ **/
 struct fastbuf *fbsock_create(struct fbsock_params *par);
 
 #endif
diff --git a/ucw/ff-unicode.h b/ucw/ff-unicode.h
index 58c75d85..c3d2300c 100644
--- a/ucw/ff-unicode.h
+++ b/ucw/ff-unicode.h
@@ -15,7 +15,7 @@
 #include "ucw/fastbuf.h"
 #include "ucw/unicode.h"
 
-/*** UTF-8 ***/
+/* ** UTF-8 ** */
 
 int bget_utf8_slow(struct fastbuf *b, uns repl);
 int bget_utf8_32_slow(struct fastbuf *b, uns repl);
@@ -48,20 +48,17 @@ bget_utf8_32_repl(struct fastbuf *b, uns repl)
     return bget_utf8_32_slow(b, repl);
 }
 
-static inline int
-bget_utf8(struct fastbuf *b)
+static inline int bget_utf8(struct fastbuf *b) /** Read a single utf8 character from range [0, 0xffff]. **/
 {
   return bget_utf8_repl(b, UNI_REPLACEMENT);
 }
 
-static inline int
-bget_utf8_32(struct fastbuf *b)
+static inline int bget_utf8_32(struct fastbuf *b) /** Read a single utf8 character (from the whole unicode range). **/
 {
   return bget_utf8_32_repl(b, UNI_REPLACEMENT);
 }
 
-static inline void
-bput_utf8(struct fastbuf *b, uns u)
+static inline void bput_utf8(struct fastbuf *b, uns u) /** Write a single utf8 character from range [0, 0xffff]. **/
 {
   if (bavailw(b) >= 3)
     b->bptr = utf8_put(b->bptr, u);
@@ -69,8 +66,7 @@ bput_utf8(struct fastbuf *b, uns u)
     bput_utf8_slow(b, u);
 }
 
-static inline void
-bput_utf8_32(struct fastbuf *b, uns u)
+static inline void bput_utf8_32(struct fastbuf *b, uns u) /** Write a single utf8 character (from the whole unicode range). **/
 {
   if (bavailw(b) >= 6)
     b->bptr = utf8_32_put(b->bptr, u);
@@ -78,7 +74,7 @@ bput_utf8_32(struct fastbuf *b, uns u)
     bput_utf8_32_slow(b, u);
 }
 
-/*** UTF-16 ***/
+/* ** UTF-16 ** */
 
 int bget_utf16_be_slow(struct fastbuf *b, uns repl);
 int bget_utf16_le_slow(struct fastbuf *b, uns repl);
@@ -111,20 +107,29 @@ bget_utf16_le_repl(struct fastbuf *b, uns repl)
     return bget_utf16_le_slow(b, repl);
 }
 
-static inline int
-bget_utf16_be(struct fastbuf *b)
+/**
+ * Read an utf16 character from fastbuf.
+ * Big endian version.
+ **/
+static inline int bget_utf16_be(struct fastbuf *b)
 {
   return bget_utf16_be_repl(b, UNI_REPLACEMENT);
 }
 
-static inline int
-bget_utf16_le(struct fastbuf *b)
+/**
+ * Read an utf16 character from fastbuf.
+ * Little endian version.
+ **/
+static inline int bget_utf16_le(struct fastbuf *b)
 {
   return bget_utf16_le_repl(b, UNI_REPLACEMENT);
 }
 
-static inline void
-bput_utf16_be(struct fastbuf *b, uns u)
+/**
+ * Write an utf16 character to fastbuf.
+ * Big endian version.
+ **/
+static inline void bput_utf16_be(struct fastbuf *b, uns u)
 {
   if (bavailw(b) >= 4)
     b->bptr = utf16_be_put(b->bptr, u);
@@ -132,8 +137,11 @@ bput_utf16_be(struct fastbuf *b, uns u)
     bput_utf16_be_slow(b, u);
 }
 
-static inline void
-bput_utf16_lbe(struct fastbuf *b, uns u)
+/**
+ * Write an utf16 character to fastbuf.
+ * Little endian version.
+ **/
+static inline void bput_utf16_lbe(struct fastbuf *b, uns u)
 {
   if (bavailw(b) >= 4)
     b->bptr = utf16_le_put(b->bptr, u);