ICU-157 add some more documentation comments

X-SVN-Rev: 255

icu4c/source/common/ucnv_io.h

@@ -20,21 +20,53 @@
 
 #include "utypes.h"
 
+/**
+ * Map a converter alias name to a canonical converter name.
+ * The alias is searched for case-insensitively, the converter name
+ * is returned in mixed-case.
+ * Returns NULL if the alias is not found.
+ */
 U_CFUNC const char *
 ucnv_io_getConverterName(const char *alias, UErrorCode *pErrorCode);
 
+/**
+ * Search case-insensitively for a converter alias and set aliases to
+ * a pointer to the list of aliases for the actual converter.
+ * The first "alias" is the canonical converter name.
+ * The aliases are stored consecutively, in mixed case, each NUL-terminated.
+ * There are as many strings in this list as the return value specifies.
+ * Returns the number of aliases including the canonical converter name,
+ * or 0 if the alias is not found.
+ */
 U_CFUNC uint16_t
 ucnv_io_getAliases(const char *alias, const char **aliases, UErrorCode *pErrorCode);
 
+/**
+ * Search case-insensitively for a converter alias and return
+ * the (index)th alias.
+ * Returns NULL if the alias is not found.
+ */
 U_CFUNC const char *
 ucnv_io_getAlias(const char *alias, uint16_t index, UErrorCode *pErrorCode);
 
+/**
+ * Return the number of all aliases (and converter names).
+ */
 U_CFUNC uint16_t
 ucnv_io_countAvailableAliases(UErrorCode *pErrorCode);
 
+/**
+ * Return the (index)th alias or converter name in mixed case, or NULL
+ * if there is none (typically, if the data cannot be loaded).
+ * 0<=index<=ucnv_io_countAvailableAliases().
+ */
 U_CFUNC const char *
 ucnv_io_getAvailableAlias(uint16_t index, UErrorCode *pErrorCode);
 
+/**
+ * Fill an array const char *aliases[ucnv_io_countAvailableAliases()]
+ * with pointers to all aliases and converter names in mixed-case.
+ */
 U_CFUNC void
 ucnv_io_fillAvailableAliases(const char **aliases, UErrorCode *pErrorCode);
 

icu4c/source/common/udata.h

@@ -33,6 +33,10 @@
  * is affected by the properties - if there is integer data
  * with word sizes > 1 byte, char* text, or UChar* text.</p>
  *
+ * <p>The implementation for the <code>udata_open[Choice]()</code>
+ * functions may reject data based on the value in <code>isBigEndian</code>.
+ * No other field is used by the <code>udata</code> API implementation.</p>
+ *
  * <p>The <code>dataFormat</code> may be used to identify
  * the kind of data, e.g. a converter table.</p>
  *
@@ -85,6 +89,14 @@ typedef struct UDataMemory UDataMemory;
 
 /**
  * Callback function for udata_openChoice().
+ * @param context parameter passed into <code>udata_openChoice()</code>.
+ * @param type The type of the data as passed into <code>udata_openChoice()</code>.
+ *             It may be <code>NULL</code>.
+ * @param name The name of the data as passed into <code>udata_openChoice()</code>.
+ * @param pInfo A pointer to the <code>UDataInfo</code> structure
+ *              of data that has been loaded and will be returned
+ *              by <code>udata_openChoice()</code> if this function
+ *              returns <code>TRUE</code>.
  * @return TRUE if the current data memory is acceptable
  */
 typedef bool_t
@@ -104,7 +116,61 @@ udata_open(const char *path, const char *type, const char *name,
            UErrorCode *pErrorCode);
 
 /**
+ * Data loading function.
+ * This function is used to find and load efficiently data for
+ * ICU and applications using ICU.
+ * It provides an abstract interface that allows to specify a data
+ * type and name to find and load the data.
  *
+ * <p>The implementation depends on platform properties and user preferences
+ * and may involve loading shared libraries (DLLs), mapping
+ * files into memory, or fopen()/fread() files.
+ * It may also involve using static memory or database queries etc.
+ * Several or all data items may be combined into one entity
+ * (DLL, memory-mappable file).</p>
+ *
+ * <p>The data is always preceded by a header that includes
+ * a <code>UDataInfo</code> structure.
+ * The caller's <code>isAcceptable()</code> function is called to make
+ * sure that the data is useful. It may be called several times if it
+ * rejects the data and there is more than one location with data
+ * matching the type and name.</p>
+ *
+ * <p>If <code>path==NULL</code>, then ICU data is loaded.
+ * Otherwise, it is separated into a basename and a basename-less path string.
+ * If the path string is empty, then <code>u_getDataDirectory()</code>
+ * is set in its place.
+ * When data is loaded from files or DLLs (shared libraries) and
+ * may be stored in common files, then the data finding is roughly as follows:
+ * <ul>
+ *     <li>common file at path/basename has entry name_type?</li>
+ *     <li>common file at basename has entry name_type?</li>
+ *     <li>separate file at path/basename_name_type?</li>
+ *     <li>separate file at basename_name_type?</li>
+ *     <li>separate file at path/name_type?</li>
+ *     <li>separate file at name_type?</li>
+ * </ul>
+ * If the basename is empty, then only the last two options are attempted.
+ * Otherwise, it serves as a name for a common data file or as a basename
+ * (collection name) prefix for individual files.</p>
+ *
+ * @param path Specifies an absolute path and/or a basename for the
+ *             finding of the data in the file system.
+ *             <code>NULL</code> for ICU data.
+ * @param type A string that specifies the type of data to be loaded.
+ *             For example, resource bundles are loaded with type "res",
+ *             conversion tables with type "cnv".
+ *             This may be <code>NULL</code> or empty.
+ * @param name A string that specifies the name of the data.
+ * @param isAcceptable This function is called to verify that loaded data
+ *                     is useful for the client code. If it returns FALSE
+ *                     for all data items, then <code>udata_openChoice()</code>
+ *                     will return with an error.
+ * @param context Arbitrary parameter to be passed into isAcceptable.
+ * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>.
+ * @return A pointer (handle) to a data memory object, or <code>NULL</code>
+ *         if an error occurs. Call <code>udata_getMemory()</code>
+ *         to get a pointer to the actual data.
  */
 U_CAPI UDataMemory * U_EXPORT2
 udata_openChoice(const char *path, const char *type, const char *name,
@@ -121,6 +187,7 @@ udata_close(UDataMemory *pData);
 
 /**
  * Get the pointer to the actual data inside the data memory.
+ * The data is read-only.
  */
 U_CAPI const void * U_EXPORT2
 udata_getMemory(UDataMemory *pData);