From 3cebf9b4c3d027dc0d6e75d43967007ecab9a200 Mon Sep 17 00:00:00 2001
From: "tg(x)" <*@tg-x.net>
Date: Wed, 4 May 2011 01:30:09 +0200
Subject: [PATCH] text: docs

---
 include/psyc/parser.h | 16 ++++----
 include/psyc/render.h |  4 +-
 include/psyc/text.h   | 85 +++++++++++++++++++++++++++++++++++--------
 3 files changed, 80 insertions(+), 25 deletions(-)

diff --git a/include/psyc/parser.h b/include/psyc/parser.h
index 87de724..dc6c378 100644
--- a/include/psyc/parser.h
+++ b/include/psyc/parser.h
@@ -7,7 +7,7 @@
 */
 
 /**
- * @defgroup parsing Parsing Functions
+ * @defgroup parser Parsing Functions
  *
  * This module contains all parsing functions.
  * @{
@@ -126,9 +126,9 @@ typedef struct
 } psycParseListState;
 
 /**
- * Initiates the state struct.
+ * Initializes the state struct.
  *
- * @param state Pointer to the state struct that should be initiated.
+ * @param state Pointer to the state struct that should be initialized.
  */
 static inline
 void psyc_initParseState (psycParseState* state)
@@ -137,9 +137,9 @@ void psyc_initParseState (psycParseState* state)
 }
 
 /**
- * Initiates the state struct with flags.
+ * Initializes the state struct with flags.
  *
- * @param state Pointer to the state struct that should be initiated.
+ * @param state Pointer to the state struct that should be initialized.
  * @param flags Flags to be set for the parser, see psycParseFlag.
  */
 static inline
@@ -187,9 +187,9 @@ void psyc_setParseBuffer2 (psycParseState* state, char *buffer, size_t length)
 }
 
 /**
- * Initiates the list state struct.
+ * Initializes the list state struct.
  *
- * @param state Pointer to the list state struct that should be initiated.
+ * @param state Pointer to the list state struct that should be initialized.
  */
 static inline
 void psyc_initParseListState (psycParseListState* state)
@@ -241,4 +241,4 @@ psycParseListRC psyc_parseList (psycParseListState* state, psycString *name, psy
 
 #endif // PSYC_PARSER_H
 
-/** @} */ // end of parsing group
+/** @} */ // end of parser group
diff --git a/include/psyc/render.h b/include/psyc/render.h
index bf7ebcb..c2d988c 100644
--- a/include/psyc/render.h
+++ b/include/psyc/render.h
@@ -12,7 +12,7 @@
  */
 
 /**
- * @defgroup rendering Rendering Functions
+ * @defgroup render Rendering Functions
  *
  * This module contains all rendering functions.
  * @{
@@ -40,4 +40,4 @@ psycRenderRC psyc_renderList (psycList *list, char *buffer, size_t buflen);
 
 #endif // PSYC_RENDER_H
 
-/** @} */ // end of rendering group
+/** @} */ // end of render group
diff --git a/include/psyc/text.h b/include/psyc/text.h
index a9f25b3..606fc1f 100644
--- a/include/psyc/text.h
+++ b/include/psyc/text.h
@@ -1,18 +1,41 @@
 /**
- * The return value definitions for the PSYC text parsing function.
- * @see psyc_text()
+ * @file psyc/text.h
+ * @brief Interface for text template rendering.
+ *
+ * All text template functions and the definitions they use are
+ * defined in this file.
  */
 
+/**
+ * @defgroup text Text template functions
+ *
+ * This module contains all text template functions.
+ * @{
+ */
+
+/**
+ * Return values for the text template parsing function.
+ * @see psyc_text()
+ */
 typedef enum
 {
+	/// No substitution was made, nothing was written to the buffer.
 	PSYC_TEXT_NO_SUBST = -1,
+	/// Text template parsing & rendering complete.
 	PSYC_TEXT_COMPLETE = 0,
+	/// Text template parsing & rendering is incomplete, because the buffer was too small.
+	/// Another call is required to this function with a new buffer.
 	PSYC_TEXT_INCOMPLETE = 1,
 } psycTextRC;
 
+/**
+ * Return values for psycTextCB.
+ */
 typedef enum
 {
+	/// Value not found, don't substitute anything.
 	PSYC_TEXT_VALUE_NOT_FOUND = -1,
+	/// Value found, substitute contents of the value variable.
 	PSYC_TEXT_VALUE_FOUND = 0,
 } psycTextValueRC;
 
@@ -33,13 +56,23 @@ typedef struct
  * Callback for psyc_text() that produces a value for a match.
  *
  * The application looks up a match such as _fruit from [_fruit] and
- * if found writes its current value from its variable store into the
- * outgoing buffer.. "Apple" for example. The template returns the
- * number of bytes written. 0 is a legal return value. Should the
- * callback return -1, psyc_text leaves the original template text as is.
+ * if found sets value->ptr & value->length to point to the found value,
+ * "Apple" for example. 0 is a legal value for the length.
+ * The callbacks returns either PSYC_TEXT_VALUE_FOUND or
+ * PSYC_TEXT_VALUE_NOT_FOUND if no match found in which case psyc_text
+ * leaves the original template text as is.
  */
 typedef psycTextValueRC (*psycTextCB)(const char *name, size_t len, psycString *value);
 
+/**
+ * Initializes the PSYC text state struct.
+ *
+ * @param state Pointer to the PSYC text state struct that should be initialized.
+ * @param template Text template to be parsed.
+ * @param tlen Length of template.
+ * @param buffer Buffer where the rendered text is going to be written.
+ * @param blen Length of buffer.
+ */
 static inline
 void psyc_initTextState (psycTextState *state,
                          char *template, size_t tlen,
@@ -52,6 +85,19 @@ void psyc_initTextState (psycTextState *state,
 	state->close = psyc_newString("]", 1);
 }
 
+/**
+ * Initializes the PSYC text state struct with custom open & closing braces.
+ *
+ * @param state Pointer to the PSYC text state struct that should be initialized.
+ * @param template Text template to be parsed.
+ * @param tlen Length of template.
+ * @param buffer Buffer where the rendered text is going to be written.
+ * @param blen Length of buffer.
+ * @param open Opening brace.
+ * @param openlen Length of opening brace.
+ * @param close Closing brace.
+ * @param closelen Length of closing brace.
+ */
 static inline
 void psyc_initTextState2 (psycTextState* state,
                           char *template, size_t tlen,
@@ -65,6 +111,9 @@ void psyc_initTextState2 (psycTextState* state,
 	state->close = psyc_newString(close, closelen);
 }
 
+/**
+ * Sets a new buffer in the PSYC text state struct.
+ */
 static inline
 void psyc_setTextBuffer (psycTextState* state, psycString buffer)
 {
@@ -72,6 +121,9 @@ void psyc_setTextBuffer (psycTextState* state, psycString buffer)
 	state->written = 0;
 }
 
+/**
+ * Sets a new buffer in the PSYC text state struct.
+ */
 static inline
 void psyc_setTextBuffer2 (psycTextState* state,
                           char *buffer, size_t length)
@@ -82,15 +134,18 @@ void psyc_setTextBuffer2 (psycTextState* state,
 /**
  * Fills out text templates by asking a callback for content.
  *
- * Copies the contents of the template into the buffer while looking
- * for braceOpen and braceClose strings and calling the callback for
- * each enclosed string between these braces. Should the callback
- * return -1, the original template text is copied as is.
+ * Copies the contents of the template into the buffer while looking for the
+ * opening and closing brace strings and calling the callback for each enclosed
+ * string between these braces. Should the callback return
+ * PSYC_TEXT_VALUE_NOT_FOUND, the original template text is copied as is.
  *
- * By default PSYC's "[" and "]" are used but you can provide any other
- * brace strings such as "${" and "}" or "<!--" and "-->".
+ * Before calling this function psyc_initTextState or psyc_initTextState should
+ * be called to initialze the state struct. By default PSYC's "[" and "]" are
+ * used but you can provide any other brace strings such as "${" and "}" or
+ * "<!--" and "-->".
  *
- * See also http://about.psyc.eu/psyctext
- */
-
+ * @see http://about.psyc.eu/psyctext
+ **/
 psycTextRC psyc_text (psycTextState *state, psycTextCB getValue);
+
+/** @} */ // end of text group