From 963dacdb0d633a1704f66d3e3126d928ede5210b Mon Sep 17 00:00:00 2001
From: "Steven R. Loomis" <srl@icu-project.org>
Date: Sat, 9 Dec 2000 02:37:17 +0000
Subject: [PATCH] ICU-647 more documentation updates

X-SVN-Rev: 3185
---
 icu4c/source/common/unicode/ucnv.h    |  9 ++---
 icu4c/source/common/unicode/ucnv_cb.h | 52 ++++++++++++++-------------
 2 files changed, 30 insertions(+), 31 deletions(-)

diff --git a/icu4c/source/common/unicode/ucnv.h b/icu4c/source/common/unicode/ucnv.h
index e819936c481..e1a3f38b92d 100644
--- a/icu4c/source/common/unicode/ucnv.h
+++ b/icu4c/source/common/unicode/ucnv.h
@@ -18,12 +18,10 @@
 
 /**
  * \file
- * \brief Description of character convrersion C API
+ * \brief Description of character conversion C API
  *
  * <h2>Character Conversion C API </h2>
  *
- * Character Conversion C API documentation is still under construction. 
- * Please check for updates soon.
  */
 
 #ifndef UCNV_H
@@ -874,13 +872,12 @@ ucnv_convert (const char *toConverterName,
 
 
 /**
- * SYSTEM API
  * Frees up memory occupied by unused, cached converter shared data.
  *
  * @return the number of cached converters successfully deleted
  * @see ucnv_close
  * @stable
- * @system
+ * @system SYSTEM API
  */
 U_CAPI int32_t U_EXPORT2
 ucnv_flushCache (void);
@@ -998,7 +995,7 @@ ucnv_getDefaultName (void);
  * and preserve it indefinitely. 
  * @param name the converter name to be the default (must exist).
  * @see ucnv_getDefaultName
- * @system
+ * @system SYSTEM API
  */
 U_CAPI void U_EXPORT2
 ucnv_setDefaultName (const char *name);
diff --git a/icu4c/source/common/unicode/ucnv_cb.h b/icu4c/source/common/unicode/ucnv_cb.h
index e842d348c79..dc40d1c439b 100644
--- a/icu4c/source/common/unicode/ucnv_cb.h
+++ b/icu4c/source/common/unicode/ucnv_cb.h
@@ -14,7 +14,7 @@
 
 /**
  * \file 
- * \brief Description of callback C API for ICU's codeset conversion library
+ * \brief Description of converter callback C API
  *
  * <h2> Callback API for ICU's codeset conversion libray </h2>
  *
@@ -27,43 +27,45 @@
 #include "unicode/ucnv.h"
 #include "unicode/ucnv_err.h"
 
-/* From Unicode */
 /**
- * Used by the callback functions.  This function will write out the error
- * character(s) to the target byte buffer.
+ * Used by FromU callback functions.  Writes out the specified byte output bytes to the target
+ * byte buffer or to converter internal buffers.
  *
- * @param args : callback fromUnicode arguments
- * @param target : output target buffer of the callback result.
- * @param length : the length of target buffer
- * @param offsetIndex : the relative offset index from callback.
- * @param err error status <TT>U_BUFFER_OVERFLOW</TT>
+ * @param args callback fromUnicode arguments
+ * @param source source bytes to write
+ * @param length length of bytes to write
+ * @param offsetIndex the relative offset index from callback.
+ * @param err error status. If <TT>U_BUFFER_OVERFLOW</TT> is returned, then U_BUFFER_OVERFLOW <STRONG>must</STRONG> 
+ * be returned to the user, because it means that not all data could be written into the target buffer, and some is 
+ * in the converter error buffer.
  * @see ucnv_cbFromUWriteSub
  * @draft
  */
 
-U_CAPI void U_EXPORT2 ucnv_cbFromUWriteBytes (UConverterFromUnicodeArgs *args,
-                       const char* source,
-                       int32_t length,
-                       int32_t offsetIndex,
-                       UErrorCode * err);
+U_CAPI void U_EXPORT2
+ucnv_cbFromUWriteBytes (UConverterFromUnicodeArgs *args,
+                        const char* source,
+                        int32_t length,
+                        int32_t offsetIndex,
+                        UErrorCode * err);
 
 /**
- * Used by the callback functions.  This function will write out the error
- * character(s) to the substitution character.
+ * Used by FromU callback functions.  This function will write out the
+ * correct substitution character sequence to the target.
  *
- * @param args : callback fromUnicode arguments
- * @param target : output target buffer of the callback result.
- * @param length : the length of target buffer
- * @param offsetIndex : the relative offset index from callback.
- * @param err error status <TT>U_BUFFER_OVERFLOW</TT>
+ * @param args callback fromUnicode arguments
+ * @param offsetIndex the relative offset index from the current source pointer to be used
+ * @param err error status. If <TT>U_BUFFER_OVERFLOW</TT> is returned, then U_BUFFER_OVERFLOW <STRONG>must</STRONG> 
+ * be returned to the user, because it means that not all data could be written into the target buffer, and some is 
+ * in the converter error buffer.
  * @see ucnv_cbFromUWriteBytes
  * @draft
  */
 
-U_CAPI void U_EXPORT2 ucnv_cbFromUWriteSub (UConverterFromUnicodeArgs *args,
-                       int32_t offsetIndex,
-                       UErrorCode * err);
-
+U_CAPI void U_EXPORT2 
+ucnv_cbFromUWriteSub (UConverterFromUnicodeArgs *args,
+                      int32_t offsetIndex,
+                      UErrorCode * err);
 
 /**
  * Used by the callback functions.  This function will write out the error