From 1e6a689c28d0d91c50008e5dd26f749c5cc5c5ed Mon Sep 17 00:00:00 2001
From: Alexander Vdolainen <avdolainen@zoho.com>
Date: Sat, 26 Oct 2019 04:08:27 +0300
Subject: [PATCH] Description for new cstr wrapper is done.

---
 include/sexpr/sexp.h | 59 ++++++++++++++++++++++++++++++++------------
 1 file changed, 43 insertions(+), 16 deletions(-)

diff --git a/include/sexpr/sexp.h b/include/sexpr/sexp.h
index 87ff562..4401050 100644
--- a/include/sexpr/sexp.h
+++ b/include/sexpr/sexp.h
@@ -567,12 +567,29 @@ typedef struct sexp_iowrap {
   size_t cnt;
 } sexp_iowrap_t;
 
-/* TODO: doxygen? more doxygen */
+/**
+ * \ingroup IO
+ * This structure is a wrapper around a the parsing infrastructure (continuation
+ * and a buffer) required to parse off of it.  This is used so that routines can
+ * hide the loops and details required to accumulate up data read off of the buffer.
+ */
 typedef struct sexp_cstrwrap {
+  /**
+   * Continuation used to parse off of the given buffer
+   */
   pcont_t *cc;
+  /**
+   * A pointer to the cstring data to parse
+   */
   const char *seval;
+  /**
+   * different counters used to have a deal with source and buffer
+   */
   size_t rl, cnt;
   size_t sln;
+  /**
+   * Temproary buffer used to parse
+   */
   char buf[CSTRBUFSIZ];
 } sexp_cstrwrap_t;
 
@@ -629,7 +646,7 @@ extern "C" {
    * return an allocated sexp_t.  This structure may be an already allocated
    * one from the stack or a new one if none are available.  Use this instead
    * of manually mallocing if you want to avoid excessive mallocs.  <I>Note:
-   * Mallocing your own expressions is fine - you can even use 
+   * Mallocing your own expressions is fine - you can even use
    * sexp_t_deallocate to deallocate them and put them in the pool.</I>
    * Also, if the stack has not been initialized yet, this does so.
    */
@@ -641,7 +658,7 @@ extern "C" {
    * allocated already.
    */
   void sexp_t_deallocate(sexp_t *s);
-  
+
   /**
    * In the event that someone wants us to release ALL of the memory used
    * between calls by the library, they can free it.  If you don't call
@@ -689,7 +706,7 @@ extern "C" {
    * element is carrying a binary pointer only.
    */
   sexp_t *new_sexp_binary_atom(char *data, size_t binlength);
-  
+
   /**
    * Allocate a new sexp_t element representing a value.  The user must
    * specify the precise type of the atom.  This used to default to
@@ -701,9 +718,9 @@ extern "C" {
    * wanted.
    */
   sexp_t *new_sexp_atom(const char *buf, size_t bs, atom_t aty);
-    
-  /** 
-   * create an initial continuation for parsing the given string 
+
+  /**
+   * create an initial continuation for parsing the given string
    */
   pcont_t *init_continuation(char *str);
 
@@ -730,7 +747,7 @@ extern "C" {
   void destroy_iowrap(sexp_iowrap_t *iow);
 
   /**
-   * \ingroup IO 
+   * \ingroup IO
    * given and IO wrapper handle, read one s-expression
    * off of it.  this expression may be contained in a continuation,
    * so there is no guarantee that under the covers an IO read
@@ -742,32 +759,42 @@ extern "C" {
    */
   sexp_t *read_one_sexp(sexp_iowrap_t *iow);
 
+  /**
+   * \ingroup IO
+   * create an wrapper structure around a c string buffer.  A NULL return
+   * value indicates some problem occurred allocating the wrapper, so the
+   * user should check the value of sexp_errno for further information.
+   */
   sexp_cstrwrap_t *init_cstrwrap(const char *);
 
+  /**
+   * \ingroup IO
+   * destroy a wrapper structure.
+   */
   void destroy_cstrwrap(sexp_cstrwrap_t *);
 
   sexp_t *get_one_sexp(sexp_cstrwrap_t *);
 
-  /** 
+  /**
    * \ingroup parser
-   * wrapper around parser for compatibility. 
+   * wrapper around parser for compatibility.
    */
   sexp_t *parse_sexp(char *s, size_t len);
 
-  /** 
+  /**
    * \ingroup parser
-   * wrapper around parser for friendlier continuation use 
-   * pre-condition : continuation (cc) is NON-NULL! 
+   * wrapper around parser for friendlier continuation use
+   * pre-condition : continuation (cc) is NON-NULL!
    */
   sexp_t *iparse_sexp(char *s, size_t len, pcont_t *cc);
-  
+
   /**
    * \ingroup parser
    * given a LISP style s-expression string, parse it into a set of
-   * connected sexp_t structures. 
+   * connected sexp_t structures.
    */
   pcont_t *cparse_sexp(char *s, size_t len, pcont_t *pc);
-  
+
   /**
    * given a sexp_t structure, free the memory it uses (and recursively free
    * the memory used by all sexp_t structures that it references).  Note