From 47db800079d3df8e8adfd93b466795d0803dabe8 Mon Sep 17 00:00:00 2001
From: Adam Dickmeiss <adam@indexdata.dk>
Date: Sun, 1 Mar 2009 23:26:46 +0100
Subject: [PATCH] Document a little.

---
 include/yaz/icu.h |   47 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/include/yaz/icu.h b/include/yaz/icu.h
index 4d62e1e..23126ab 100644
--- a/include/yaz/icu.h
+++ b/include/yaz/icu.h
@@ -41,27 +41,72 @@
 
 YAZ_BEGIN_CDECL
 
+/** \brief opaque ICU chain */
 typedef struct icu_chain *yaz_icu_chain_t;
 
+/** \brief destroys ICU chain */
 YAZ_EXPORT void icu_chain_destroy(yaz_icu_chain_t chain);
 
+/** \brief constructs ICU chain from XML specification
+    \param \param xml_node icu_chain XML node - with attribute locale in it
+    \param \param sort 1 if ICU chain is to deal with sort keys; 0 otherwise
+    \param \param status May include ICU error code on failure
+    \returns chain ptr or NULL on failure in which case status may hold info
+*/
 YAZ_EXPORT yaz_icu_chain_t icu_chain_xml_config(const xmlNode *xml_node,
                                                 int sort,
                                                 UErrorCode * status);
-
+/** \brief pass string to ICU for parsing/tokenization/etc
+    \param chain ICU chain to be used for parsing
+    \param src8cstr input C string (\0-terminated)
+    \param status may include ICU error on failure
+    \retval 0 failure
+    \retval 1 success
+*/
 YAZ_EXPORT int icu_chain_assign_cstr(yaz_icu_chain_t chain,
                                      const char * src8cstr, 
                                      UErrorCode *status);
 
+/** \brief returns one token (if any)
+    \param chain ICU chain
+    \param status may include ICU error on failure
+    \retval 0 error or end-of-tokens (no more tokens)
+    \retval >0 token number (1, 3, 3, ..)
+
+    This function tries to move to "next" token in assigned
+    C-string .. Or returns 0 if no more is to be found
+*/
 YAZ_EXPORT int icu_chain_next_token(yaz_icu_chain_t chain,
                                     UErrorCode *status);
 
+/** \brief returns token number of last token processed
+    \brief chain ICU chain
+    \returns token number (numbered from 1)
+*/
 YAZ_EXPORT int icu_chain_token_number(yaz_icu_chain_t chain);
 
+/** \brief returns display token of last token processed
+    \param chain ICU chain
+    \returns display token string (C string)
+    This function returns display string for last token returned
+    by icu_chain_next_token.
+*/
 YAZ_EXPORT const char * icu_chain_token_display(yaz_icu_chain_t chain);
 
+/** \brief returns normalized token of last token processed
+    \param chain ICU chain
+    \returns normalized token string (C string)
+    This function returns normalized string for last token returned
+    by icu_chain_next_token.
+*/
 YAZ_EXPORT const char * icu_chain_token_norm(yaz_icu_chain_t chain);
 
+/** \brief returns sortkey token of last token processed
+    \param chain ICU chain
+    \returns sortkey token string (C string)
+    This function returns sortkey string for last token returned
+    by icu_chain_next_token.
+*/
 YAZ_EXPORT const char * icu_chain_token_sortkey(yaz_icu_chain_t chain);
 
 YAZ_END_CDECL
-- 
1.7.10.4