From e4b933f6f171b930160bc8a9783b61dfd700470a Mon Sep 17 00:00:00 2001 From: Vladimir Weinstein Date: Wed, 3 Nov 1999 18:20:21 +0000 Subject: [PATCH] ICU-35 header files comments updated so that Doc++ doesn't produce broken links X-SVN-Rev: 161 --- icu4c/source/common/putil.h | 2 + icu4c/source/common/scsu.h | 2 +- icu4c/source/common/ubidi.h | 15 +- icu4c/source/common/uchar.h | 171 +++++++++++++++++++++-- icu4c/source/common/ucnv.h | 17 ++- icu4c/source/common/ucnv_bld.h | 2 +- icu4c/source/common/uloc.h | 36 ++--- icu4c/source/common/ures.h | 217 +++++++++++++++-------------- icu4c/source/common/ustring.h | 5 +- icu4c/source/common/utypes.h | 15 +- icu4c/source/i18n/ubrk.h | 12 +- icu4c/source/i18n/ucal.h | 7 +- icu4c/source/i18n/ucol.h | 25 +++- icu4c/source/i18n/udat.h | 10 +- icu4c/source/i18n/unum.h | 9 +- icu4c/source/tools/ctestfw/ctest.h | 20 ++- 16 files changed, 397 insertions(+), 168 deletions(-) diff --git a/icu4c/source/common/putil.h b/icu4c/source/common/putil.h index 67cb303b03f..42428867b49 100644 --- a/icu4c/source/common/putil.h +++ b/icu4c/source/common/putil.h @@ -71,6 +71,7 @@ U_CAPI void U_EXPORT2 icu_longBitsFromDouble(double d, int32_t *hi, uint32_t */ /** * Returns the common log of the double value d. + * * @param d the double value to apply the common log function for. * @return the log of value d. */ @@ -78,6 +79,7 @@ U_CAPI int16_t U_EXPORT2 icu_log10(double d); /** * Returns the number of digits after the decimal point in a double number x. + * * @param x the double number */ U_CAPI int32_t U_EXPORT2 icu_digitsAfterDecimal(double x); diff --git a/icu4c/source/common/scsu.h b/icu4c/source/common/scsu.h index 2ad89d52141..264dea8482b 100644 --- a/icu4c/source/common/scsu.h +++ b/icu4c/source/common/scsu.h @@ -31,7 +31,7 @@ /* Maximum value for a window's index */ #define USCSU_MAX_INDEX 0xFF -/** The size of the internal buffer for a UnicodeCompressor */ +/* The size of the internal buffer for a UnicodeCompressor. */ #define USCSU_BUFSIZE 3 /** The UnicodeCompressor struct */ diff --git a/icu4c/source/common/ubidi.h b/icu4c/source/common/ubidi.h index 725fc50c742..c2185bea49f 100644 --- a/icu4c/source/common/ubidi.h +++ b/icu4c/source/common/ubidi.h @@ -109,19 +109,26 @@ DOCXX_TAG */ typedef uint8_t UBiDiLevel; -/** @memo If there is no strong character, then set the paragraph level to 0 (left-to-right). */ +/** Paragraph level setting. + * If there is no strong character, then set the paragraph level to 0 (left-to-right). + */ #define UBIDI_DEFAULT_LTR 0xfe -/** @memo If there is no strong character, then set the paragraph level to 1 (right-to-left). */ +/** Paragraph level setting. + * If there is no strong character, then set the paragraph level to 1 (right-to-left). + */ #define UBIDI_DEFAULT_RTL 0xff /** - * @memo Maximum explicit embedding level + * Maximum explicit embedding level. * (The maximum resolved level can be up to UBIDI_MAX_EXPLICIT_LEVEL+1). + * */ #define UBIDI_MAX_EXPLICIT_LEVEL 61 -/** @memo Bit flag for level input: overrides directional properties. */ +/** Bit flag for level input. + * Overrides directional properties. + */ #define UBIDI_LEVEL_OVERRIDE 0x80 /** diff --git a/icu4c/source/common/uchar.h b/icu4c/source/common/uchar.h index 55b60e8cbfe..76c9b0d52a4 100644 --- a/icu4c/source/common/uchar.h +++ b/icu4c/source/common/uchar.h @@ -60,44 +60,75 @@ */ static UChar UCHAR_MAX_VALUE; -/** + + /** * Data for enumerated Unicode general category types */ - - enum UCharCategory { - U_UNASSIGNED = 0, + /** */ + U_UNASSIGNED = 0, + /** */ U_UPPERCASE_LETTER = 1, + /** */ U_LOWERCASE_LETTER = 2, + /** */ U_TITLECASE_LETTER = 3, + /** */ U_MODIFIER_LETTER = 4, + /** */ U_OTHER_LETTER = 5, + /** */ U_NON_SPACING_MARK = 6, + /** */ U_ENCLOSING_MARK = 7, + /** */ U_COMBINING_SPACING_MARK = 8, + /** */ U_DECIMAL_DIGIT_NUMBER = 9, + /** */ U_LETTER_NUMBER = 10, + /** */ U_OTHER_NUMBER = 11, + /** */ U_SPACE_SEPARATOR = 12, + /** */ U_LINE_SEPARATOR = 13, + /** */ U_PARAGRAPH_SEPARATOR = 14, + /** */ U_CONTROL_CHAR = 15, + /** */ U_FORMAT_CHAR = 16, + /** */ U_PRIVATE_USE_CHAR = 17, + /** */ U_SURROGATE = 18, + /** */ U_DASH_PUNCTUATION = 19, + /** */ U_START_PUNCTUATION = 20, + /** */ U_END_PUNCTUATION = 21, + /** */ U_CONNECTOR_PUNCTUATION = 22, + /** */ U_OTHER_PUNCTUATION = 23, + /** */ U_MATH_SYMBOL = 24, + /** */ U_CURRENCY_SYMBOL = 25, + /** */ U_MODIFIER_SYMBOL = 26, + /** */ U_OTHER_SYMBOL = 27, + /** */ U_INITIAL_PUNCTUATION = 28, + /** */ U_FINAL_PUNCTUATION = 29, + /** */ U_GENERAL_OTHER_TYPES = 30, + /** */ U_CHAR_CATEGORY_COUNT }; @@ -105,27 +136,46 @@ typedef enum UCharCategory UCharCategory; /** * This specifies the language directional property of a character set. */ - enum UCharDirection { - U_LEFT_TO_RIGHT = 0, + /** */ + U_LEFT_TO_RIGHT = 0, + /** */ U_RIGHT_TO_LEFT = 1, + /** */ U_EUROPEAN_NUMBER = 2, + /** */ U_EUROPEAN_NUMBER_SEPARATOR = 3, + /** */ U_EUROPEAN_NUMBER_TERMINATOR = 4, + /** */ U_ARABIC_NUMBER = 5, + /** */ U_COMMON_NUMBER_SEPARATOR = 6, + /** */ U_BLOCK_SEPARATOR = 7, + /** */ U_SEGMENT_SEPARATOR = 8, + /** */ U_WHITE_SPACE_NEUTRAL = 9, + /** */ U_OTHER_NEUTRAL = 10, + /** */ U_LEFT_TO_RIGHT_EMBEDDING = 11, + /** */ U_LEFT_TO_RIGHT_OVERRIDE = 12, + /** */ U_RIGHT_TO_LEFT_ARABIC = 13, + /** */ U_RIGHT_TO_LEFT_EMBEDDING = 14, + /** */ U_RIGHT_TO_LEFT_OVERRIDE = 15, + /** */ U_POP_DIRECTIONAL_FORMAT = 16, + /** */ U_DIR_NON_SPACING_MARK = 17, + /** */ U_BOUNDARY_NEUTRAL = 18, + /** */ U_CHAR_DIRECTION_COUNT }; @@ -137,94 +187,183 @@ typedef enum UCharDirection UCharDirection; /* Generated from Unicode Data files */ enum UCharScript { /* Script names */ + /** */ U_BASIC_LATIN, + /** */ U_LATIN_1_SUPPLEMENT, + /** */ U_LATIN_EXTENDED_A, + /** */ U_LATIN_EXTENDED_B, + /** */ U_IPA_EXTENSIONS, + /** */ U_SPACING_MODIFIER_LETTERS, + /** */ U_COMBINING_DIACRITICAL_MARKS, + /** */ U_GREEK, + /** */ U_CYRILLIC, + /** */ U_ARMENIAN, + /** */ U_HEBREW, + /** */ U_ARABIC, + /** */ U_SYRIAC, + /** */ U_THAANA, + /** */ U_DEVANAGARI, + /** */ U_BENGALI, + /** */ U_GURMUKHI, + /** */ U_GUJARATI, + /** */ U_ORIYA, + /** */ U_TAMIL, + /** */ U_TELUGU, + /** */ U_KANNADA, + /** */ U_MALAYALAM, + /** */ U_SINHALA, + /** */ U_THAI, + /** */ U_LAO, + /** */ U_TIBETAN, + /** */ U_MYANMAR, + /** */ U_GEORGIAN, + /** */ U_HANGUL_JAMO, + /** */ U_ETHIOPIC, + /** */ U_CHEROKEE, + /** */ U_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS, + /** */ U_OGHAM, + /** */ U_RUNIC, + /** */ U_KHMER, + /** */ U_MONGOLIAN, + /** */ U_LATIN_EXTENDED_ADDITIONAL, + /** */ U_GREEK_EXTENDED, + /** */ U_GENERAL_PUNCTUATION, + /** */ U_SUPERSCRIPTS_AND_SUBSCRIPTS, + /** */ U_CURRENCY_SYMBOLS, + /** */ U_COMBINING_MARKS_FOR_SYMBOLS, + /** */ U_LETTERLIKE_SYMBOLS, + /** */ U_NUMBER_FORMS, + /** */ U_ARROWS, + /** */ U_MATHEMATICAL_OPERATORS, + /** */ U_MISCELLANEOUS_TECHNICAL, + /** */ U_CONTROL_PICTURES, + /** */ U_OPTICAL_CHARACTER_RECOGNITION, + /** */ U_ENCLOSED_ALPHANUMERICS, + /** */ U_BOX_DRAWING, + /** */ U_BLOCK_ELEMENTS, + /** */ U_GEOMETRIC_SHAPES, + /** */ U_MISCELLANEOUS_SYMBOLS, + /** */ U_DINGBATS, + /** */ U_BRAILLE_PATTERNS, + /** */ U_CJK_RADICALS_SUPPLEMENT, + /** */ U_KANGXI_RADICALS, + /** */ U_IDEOGRAPHIC_DESCRIPTION_CHARACTERS, + /** */ U_CJK_SYMBOLS_AND_PUNCTUATION, + /** */ U_HIRAGANA, + /** */ U_KATAKANA, + /** */ U_BOPOMOFO, + /** */ U_HANGUL_COMPATIBILITY_JAMO, + /** */ U_KANBUN, + /** */ U_BOPOMOFO_EXTENDED, + /** */ U_ENCLOSED_CJK_LETTERS_AND_MONTHS, + /** */ U_CJK_COMPATIBILITY, + /** */ U_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A, + /** */ U_CJK_UNIFIED_IDEOGRAPHS, + /** */ U_YI_SYLLABLES, + /** */ U_YI_RADICALS, + /** */ U_HANGUL_SYLLABLES, + /** */ U_HIGH_SURROGATES, + /** */ U_HIGH_PRIVATE_USE_SURROGATES, + /** */ U_LOW_SURROGATES, + /** */ U_PRIVATE_USE_AREA, + /** */ U_CJK_COMPATIBILITY_IDEOGRAPHS, + /** */ U_ALPHABETIC_PRESENTATION_FORMS, + /** */ U_ARABIC_PRESENTATION_FORMS_A, + /** */ U_COMBINING_HALF_MARKS, + /** */ U_CJK_COMPATIBILITY_FORMS, + /** */ U_SMALL_FORM_VARIANTS, + /** */ U_ARABIC_PRESENTATION_FORMS_B, + /** */ U_SPECIALS, + /** */ U_HALFWIDTH_AND_FULLWIDTH_FORMS, + /** */ U_CHAR_SCRIPT_COUNT, + /** */ U_NO_SCRIPT=U_CHAR_SCRIPT_COUNT }; typedef enum UCharScript UCharScript; @@ -234,11 +373,16 @@ typedef enum UCharScript UCharScript; */ enum UCellWidth { + /** */ U_ZERO_WIDTH = 0, - U_HALF_WIDTH = 1, - U_FULL_WIDTH = 2, - U_NEUTRAL_WIDTH = 3, - U_CELL_WIDTH_COUNT + /** */ + U_HALF_WIDTH = 1, + /** */ + U_FULL_WIDTH = 2, + /** */ + U_NEUTRAL_WIDTH = 3, + /** */ + U_CELL_WIDTH_COUNT }; typedef enum UCellWidth UCellWidth; @@ -447,6 +591,7 @@ u_charType(UChar c); /** * Retrives the decimal numeric value of a digit character. + * * @param c the digit character for which to get the numeric value * @return the numeric value of ch in decimal radix. This method returns * -1 if ch is not a valid digit character. @@ -455,8 +600,8 @@ U_CAPI int32_t U_EXPORT2 u_charDigitValue(UChar c); /** - * * Returns the script associated with a character. + * * @see #UCharScript */ U_CAPI UCharScript U_EXPORT2 @@ -638,9 +783,9 @@ U_CAPI UChar U_EXPORT2 u_totitle(UChar c); /** + * The function is used to get the Unicode standard Version that is used. * - *The function is used to get the Unicode standard Version that is used - *@return the Unicode stabdard Version number + * @return the Unicode stabdard Version number */ U_CAPI const char* U_EXPORT2 u_getVersion(void); diff --git a/icu4c/source/common/ucnv.h b/icu4c/source/common/ucnv.h index aaa513ec4b0..d6d7d03df60 100644 --- a/icu4c/source/common/ucnv.h +++ b/icu4c/source/common/ucnv.h @@ -86,6 +86,7 @@ U_CAPI UConverter* U_EXPORT2 ucnv_openU (const UChar * name, /** * Creates a UConverter object using a CCSID number. + * * @param codepage : codepage # of the uconv table * @param platform : codepage's platform (now only IBM supported) * @param err error status U_MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND @@ -102,6 +103,7 @@ U_CAPI UConverter* U_EXPORT2 ucnv_openCCSID (int32_t codepage, /** * Deletes the unicode converter. + * * @param converter the converter object to be deleted * @see ucnv_open * @see ucnv_openU @@ -114,6 +116,7 @@ U_CAPI void U_EXPORT2 ucnv_close (UConverter * converter); /** * Fills in the output parameter, subChars, with the substitution characters * as multiple bytes. + * * @param converter: the Unicode converter * @param subChars: the subsitution characters * @param len: on input the capacity of subChars, on output the number of bytes copied to it @@ -152,6 +155,7 @@ U_CAPI void U_EXPORT2 /** * Fills in the output parameter, errBytes, with the error characters from the * last failing conversion. + * * @param converter: the Unicode converter * @param errBytes: the bytes in error * @param len: on input the capacity of errBytes, on output the number of bytes copied to it @@ -170,6 +174,7 @@ U_CAPI void U_EXPORT2 /** * Fills in the output parameter, errChars, with the error characters from the * last failing conversion. + * * @param converter: the Unicode converter * @param errUChars: the bytes in error * @param len: on input the capacity of errUChars, on output the number of UChars copied to it @@ -219,6 +224,7 @@ U_CAPI int8_t U_EXPORT2 * Returns the display name of the converter passed in based on the Locale passed in, * in the case the locale contains no display name, the internal ASCII name will be * filled in. + * * @param converter the Unicode converter. * @param displayLocale is the specific Locale we want to localised for * @param displayName user provided buffer to be filled in @@ -302,6 +308,7 @@ U_CAPI void U_EXPORT2 ucnv_getStarters(const UConverter* converter, /** * Gets the current calback function used by the converter when illegal or invalid sequence found. + * * @param converter the unicode converter * @return a pointer to the callback function * @see ucnv_setToUCallBack @@ -311,6 +318,7 @@ U_CAPI UConverterToUCallback U_EXPORT2 /** * Gets the current callback function used by the converter when illegal or invalid sequence found. + * * @param converter the unicode converter * @return a pointer to the callback function * @see ucnv_setFromUCallBack @@ -319,7 +327,8 @@ U_CAPI UConverterFromUCallback U_EXPORT2 ucnv_getFromUCallBack (const UConverter * converter); /** - * Gets the current callback function used by the converter when illegal or invalid sequence found + * Gets the current callback function used by the converter when illegal or invalid sequence found. + * * @param converter the unicode converter * @param action the callback function we want to set. * @param err The error code status @@ -332,7 +341,8 @@ U_CAPI UConverterToUCallback U_EXPORT2 UErrorCode * err); /** - * Gets the current callback function used by the converter when illegal or invalid sequence found + * Gets the current callback function used by the converter when illegal or invalid sequence found. + * * @param converter the unicode converter * @param action the callback function we want to set. * @param err The error code status @@ -546,6 +556,7 @@ U_CAPI /** * SYSTEM API * Iterates through every cached converter and frees all the unused ones. + * * @return the number of cached converters successfully deleted */ U_CAPI int32_t U_EXPORT2 ucnv_flushCache (void); @@ -563,6 +574,7 @@ U_CAPI /** * returns the number of available converters. + * * @return the number of available converters * @see ucnv_getAvailableName */ @@ -570,6 +582,7 @@ U_CAPI int32_t U_EXPORT2 ucnv_countAvailable (void); /** * returns the current default converter name. + * * @return returns the current default converter name * @see ucnv_setDefaultName */ diff --git a/icu4c/source/common/ucnv_bld.h b/icu4c/source/common/ucnv_bld.h index d4915c809ab..8e859909252 100644 --- a/icu4c/source/common/ucnv_bld.h +++ b/icu4c/source/common/ucnv_bld.h @@ -70,7 +70,7 @@ typedef enum { UCNV_UTF16_LittleEndian = 6, UCNV_EBCDIC_STATEFUL = 7, UCNV_ISO_2022 = 8, - /** Number of converter types for which we have conversion routines. */ + /* Number of converter types for which we have conversion routines. */ UCNV_NUMBER_OF_SUPPORTED_CONVERTER_TYPES = 9, UCNV_JIS = 9, UCNV_EUC = 10, diff --git a/icu4c/source/common/uloc.h b/icu4c/source/common/uloc.h index 298857b546d..672688f5676 100644 --- a/icu4c/source/common/uloc.h +++ b/icu4c/source/common/uloc.h @@ -172,7 +172,7 @@ * */ -/** +/* * * Useful constants for language. */ @@ -186,7 +186,7 @@ #define ULOC_SIMPLIFIED_CHINESE "zh_CN" #define ULOC_TRADITIONAL_CHINESE "zh_TW" -/** +/* * * Useful constants for country. */ @@ -207,8 +207,8 @@ /** - * * Gets the system's default locale. + * * @return the system default locale */ @@ -216,8 +216,8 @@ U_CAPI const char* U_EXPORT2 uloc_getDefault(void); /** - * * Sets the system's default locale. + * * @param localeID the new system default locale * @param status the error information if the setting of default locale fails */ @@ -226,8 +226,8 @@ uloc_setDefault(const char* localeID, UErrorCode* status); /** - * * Gets the language code for the specified locale. + * * @param localeID the locale to get the ISO langauge code with * @param language the langauge code for localeID * @param languageCapacity the size of the language buffer to store the @@ -244,8 +244,8 @@ uloc_getLanguage(const char* localeID, UErrorCode* err); /** - * * Gets the country code for the specified locale. + * * @param localeID the locale to get the country code with * @param country the country code for localeID * @param languageCapacity the size of the coutry buffer to store the @@ -262,8 +262,8 @@ uloc_getCountry(const char* localeID, UErrorCode* err); /** - * * Gets the variant code for the specified locale. + * * @param localeID the locale to get the variant code with * @param variant the variant code for localeID * @param variantCapacity the size of the variant buffer to store the @@ -279,8 +279,8 @@ uloc_getVariant(const char* localeID, int32_t variantCapacity, UErrorCode* err); /** - * * Gets the full name for the specified locale. + * * @param localeID the locale to get the full name with * @param name the full name for localeID * @param nameCapacity the size of the name buffer to store the @@ -297,8 +297,8 @@ uloc_getName(const char* localeID, UErrorCode* err); /** - * * Gets the ISO language code for the specified locale. + * * @param localeID the locale to get the ISO langauge code with * @return language the ISO langauge code for localeID */ @@ -307,8 +307,8 @@ uloc_getISO3Language(const char* localeID); /** - * * Gets the ISO country code for the specified locale. + * * @param localeID the locale to get the ISO country code with * @return country the ISO country code for localeID */ @@ -317,8 +317,8 @@ U_CAPI const char* U_EXPORT2 uloc_getISO3Country(const char* localeID); /** - * * Gets the Win32 LCID value for the specified locale. + * * @param localeID the locale to get the Win32 LCID value with * @return country the Win32 LCID for localeID */ @@ -327,8 +327,8 @@ U_CAPI uint32_t U_EXPORT2 uloc_getLCID(const char* localeID); /** - * * Gets the language name suitable for display for the specified locale. + * * @param localeID the locale to get the ISO langauge code with * @param language the displayable langauge code for localeID * @param languageCapacity the size of the language buffer to store the @@ -345,8 +345,8 @@ uloc_getDisplayLanguage(const char* locale, UErrorCode* status); /** - * * Gets the country name suitable for display for the specified locale. + * * @param localeID the locale to get the displayable country code with * @param country the displayable country code for localeID * @param languageCapacity the size of the coutry buffer to store the @@ -365,8 +365,8 @@ uloc_getDisplayCountry(const char* locale, /** - * * Gets the variant code suitable for display for the specified locale. + * * @param localeID the locale to get the displayable variant code with * @param variant the displayable variant code for localeID * @param variantCapacity the size of the variant buffer to store the @@ -384,8 +384,8 @@ uloc_getDisplayVariant(const char* locale, UErrorCode* status); /* NULL may be used to specify the default */ /** - * * Gets the full name suitable for display for the specified locale. + * * @param localeID the locale to get the displayable name with * @param variant the displayable name for localeID * @param variantCapacity the size of the name buffer to store the @@ -417,8 +417,8 @@ U_CAPI const char* U_EXPORT2 uloc_getAvailable(int32_t index); /** - * * Gets the size of the all available locale list. + * * @return the size of the locale list */ U_CAPI int32_t U_EXPORT2 uloc_countAvailable(void); @@ -446,16 +446,16 @@ U_CAPI const char* const* U_EXPORT2 uloc_getISOCountries(void); /** - * * Gets the directory containing the locale data files. + * * @return the locale data file directory */ U_CAPI const char* U_EXPORT2 uloc_getDataDirectory(void); /** - * * Sets the directory containing the locale data files. + * * @return the new directory to fetch locale data from */ diff --git a/icu4c/source/common/ures.h b/icu4c/source/common/ures.h index 7ec8c5e58e0..7ace7e3e5f9 100644 --- a/icu4c/source/common/ures.h +++ b/icu4c/source/common/ures.h @@ -33,6 +33,8 @@ #include "uloc.h" /** + * @name ResourceBundle C API + * * C API representing a collection of resource information pertaining to a given * locale. A resource bundle provides a way of accessing locale- specific information in * a data file. You create a resource bundle that manages the resources for a given @@ -116,7 +118,9 @@ * */ -/** A UResourceBundle */ +/** A UResourceBundle. + * For usage in C programs. + */ typedef void* UResourceBundle; @@ -177,62 +181,64 @@ U_CAPI UResourceBundle* U_EXPORT2 ures_openW(const wchar_t* path, UErrorCode* status); /** -* -* returns a resource string, given a resource bundle and a key -*@param resourceBundle: resourceBundle containing the desired string -*@param resourceTag: key tagging the desired string -*@param status: fills in the outgoing error code -* could be U_MISSING_RESOURCE_ERROR if the key is not found -* could be a non-failing error -* e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR -*@return: a library-owned zero-terminated unicode string (its lifetime -* is that of the resource bundle.) -*@see ures_getArrayItem -*@see ures_get2dArrayItem -*@see ures_getTaggedItem -*/ + * returns a resource string, given a resource bundle and a key. + * + * @param resourceBundle: resourceBundle containing the desired string + * @param resourceTag: key tagging the desired string + * @param status: fills in the outgoing error code + * could be U_MISSING_RESOURCE_ERROR if the key is not found + * could be a non-failing error + * e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR + * @return: a library-owned zero-terminated unicode string (its lifetime + * is that of the resource bundle.) + * @see ures_getArrayItem + * @see ures_get2dArrayItem + * @see ures_getTaggedItem + */ U_CAPI const UChar* U_EXPORT2 ures_get(const UResourceBundle* resourceBundle, const char* resourceTag, UErrorCode* status); /** -* returns a resource string which is part of an array, given a resource bundle -* a key to the array and the index of the desired string -*@param resourceBundle: resourceBundle containing the desired string -*@param resourceTag: key tagging the desired array -*@param resourceIndex: index of the desired string -*@param status: fills in the outgoing error code -* could be U_MISSING_RESOURCE_ERROR if the key is not found -* could be a non-failing error -* e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR -*@return: a library-owned zero-terminated unicode string (its lifetime -* is that of the resource bundle.) -*@see ures_get -*@see ures_get2dArrayItem -*@see ures_getTaggedItem -*/ + * Returns a resource string which is part of an array, given a resource bundle + * a key to the array and the index of the desired string. + * + * @param resourceBundle: resourceBundle containing the desired string + * @param resourceTag: key tagging the desired array + * @param resourceIndex: index of the desired string + * @param status: fills in the outgoing error code + * could be U_MISSING_RESOURCE_ERROR if the key is not found + * could be a non-failing error + * e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR + * @return: a library-owned zero-terminated unicode string (its lifetime + * is that of the resource bundle.) + * @see ures_get + * @see ures_get2dArrayItem + * @see ures_getTaggedItem + */ U_CAPI const UChar* U_EXPORT2 ures_getArrayItem(const UResourceBundle* resourceBundle, const char* resourceTag, int32_t resourceIndex, UErrorCode* status); /** -* returns a resource string which is part of a 2D array, given a resource bundle -* a key to the array and the index pair of the desired string -*@param resourceBundle: resourceBundle containing the desired string -*@param resourceTag: key tagging the desired array -*@param resourceIndex: x index of the desired string -*@param resourceIndex: y index of the desired string -*@param status: fills in the outgoing error code -* could be U_MISSING_RESOURCE_ERROR if the key is not found -* could be a non-failing error -* e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR -*@return: a library-owned zero-terminated unicode string (its lifetime -* is that of the resource bundle.) -*@see ures_get -*@see ures_getArrayItem -*@see ures_getTaggedItem -*/ + * Returns a resource string which is part of a 2D array, given a resource bundle + * a key to the array and the index pair of the desired string. + * + * @param resourceBundle: resourceBundle containing the desired string + * @param resourceTag: key tagging the desired array + * @param resourceIndex: x index of the desired string + * @param resourceIndex: y index of the desired string + * @param status: fills in the outgoing error code + * could be U_MISSING_RESOURCE_ERROR if the key is not found + * could be a non-failing error + * e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR + * @return: a library-owned zero-terminated unicode string (its lifetime + * is that of the resource bundle.) + * @see ures_get + * @see ures_getArrayItem + * @see ures_getTaggedItem + */ U_CAPI const UChar* U_EXPORT2 ures_get2dArrayItem(const UResourceBundle* resourceBundle, const char* resourceTag, @@ -241,21 +247,22 @@ U_CAPI const UChar* U_EXPORT2 ures_get2dArrayItem(const UResourceBundle* resou UErrorCode* status); /** -* returns a resource string which is part of a tagged array, given a resource bundle -* a key to the array and the key of the desired string. -*@param resourceBundle: resource bundle containing the desired string -*@param resourceTag: key tagging the desired array -*@param resourceIndex: key tagging the desired string -*@param status: fills in the outgoing error code -* could be U_MISSING_RESOURCE_ERROR if the key is not found -* could be a non-failing error -* e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR -*@return: a library-owned zero-terminated unicode string (its lifetime -* is that of the resource bundle.) -*@see ures_get -*@see ures_getArrayItem -*@see ures_get2dItem -*/ + * Returns a resource string which is part of a tagged array, given a resource bundle + * a key to the array and the key of the desired string. + * + * @param resourceBundle: resource bundle containing the desired string + * @param resourceTag: key tagging the desired array + * @param resourceIndex: key tagging the desired string + * @param status: fills in the outgoing error code + * could be U_MISSING_RESOURCE_ERROR if the key is not found + * could be a non-failing error + * e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR + * @return: a library-owned zero-terminated unicode string (its lifetime + * is that of the resource bundle.) + * @see ures_get + * @see ures_getArrayItem + * @see ures_get2dItem + */ U_CAPI const UChar* U_EXPORT2 ures_getTaggedArrayItem(const UResourceBundle* resourceBundle, const char* resourceTag, @@ -265,57 +272,57 @@ U_CAPI const UChar* U_EXPORT2 ures_getTaggedArrayItem(const UResourceBundle* r /** -* -* -*@param resourceBundle: resource bundle containing the desired strings -*@param resourceKey: key tagging the resource -*@param err: fills in the outgoing error code -* could be U_MISSING_RESOURCE_ERROR if the key is not found -* could be a non-failing error -* e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR -*@return: for Arrays: returns the number of strings in the array -* 2d Arrays: returns the number of 1d arrays -* taggedArrays: returns the number of strings in the array -* single string: returns 1 -*@see ures_get -*@see ures_getArrayItem -*@see ures_getTaggedArrayItem -*@see ures_get2dArrayItem -*/ + * Returns the number of strings/arrays in resource bundles. + * + *@param resourceBundle: resource bundle containing the desired strings + *@param resourceKey: key tagging the resource + *@param err: fills in the outgoing error code + * could be U_MISSING_RESOURCE_ERROR if the key is not found + * could be a non-failing error + * e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR + *@return: for Arrays: returns the number of strings in the array + * 2d Arrays: returns the number of 1d arrays + * taggedArrays: returns the number of strings in the array + * single string: returns 1 + *@see ures_get + *@see ures_getArrayItem + *@see ures_getTaggedArrayItem + *@see ures_get2dArrayItem + */ U_CAPI int32_t U_EXPORT2 ures_countArrayItems(const UResourceBundle* resourceBundle, const char* resourceKey, UErrorCode* err); /** -* close a resource bundle, all pointers returned from the various ures_getXXX calls -* on this particular bundle are INVALID henceforth. -* @param resourceBundle: a succesfully opened resourceBundle. -* @param status: fills in the outgoing error code -* could be U_MISSING_RESOURCE_ERROR if the key is not found -* could be a non-failing error -* e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR -* @see ures_open -* @see ures_openW -*/ + * close a resource bundle, all pointers returned from the various ures_getXXX calls + * on this particular bundle are INVALID henceforth. + * + * @param resourceBundle: a succesfully opened resourceBundle. + * @param status: fills in the outgoing error code + * could be U_MISSING_RESOURCE_ERROR if the key is not found + * could be a non-failing error + * e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR + * @see ures_open + * @see ures_openW + */ U_CAPI void U_EXPORT2 ures_close(UResourceBundle* resourceBundle); /** - * Return the version number associated with this ResourceBundle. This version - * number is a string of the form MAJOR.MINOR, where MAJOR is the version number of - * the current analytic code package, and MINOR is the version number contained in - * the resource file as the value of the tag "Version". A change in the MINOR - * version indicated an updated data file. A change in the MAJOR version indicates a - * new version of the code which is not binary-compatible with the previous version. - * If no "Version" tag is present in a resource file, the MINOR version "0" is assigned. - * - * For example, if the Collation sort key algorithm changes, the MAJOR version - * increments. If the collation data in a resource file changes, the MINOR version - * for that file increments. - * @param resourceBundle: resource bundle in question - * @return A string of the form N.n, where N is the major version number, - * representing the code version, and n is the minor version number, - * representing the resource data file. The caller does not own this - * string. - */ + * Return the version number associated with this ResourceBundle. This version + * number is a string of the form MAJOR.MINOR, where MAJOR is the version number of + * the current analytic code package, and MINOR is the version number contained in + * the resource file as the value of the tag "Version". A change in the MINOR + * version indicated an updated data file. A change in the MAJOR version indicates a + * new version of the code which is not binary-compatible with the previous version. + * If no "Version" tag is present in a resource file, the MINOR version "0" is assigned. + * For example, if the Collation sort key algorithm changes, the MAJOR version + * increments. If the collation data in a resource file changes, the MINOR version + * for that file increments. + * @param resourceBundle: resource bundle in question + * @return A string of the form N.n, where N is the major version number, + * representing the code version, and n is the minor version number, + * representing the resource data file. The caller does not own this + * string. + */ U_CAPI const char* U_EXPORT2 ures_getVersionNumber(const UResourceBundle* resourceBundle); #endif /*_URES*/ /*eof*/ diff --git a/icu4c/source/common/ustring.h b/icu4c/source/common/ustring.h index 7c69d57c687..595e4490f8c 100644 --- a/icu4c/source/common/ustring.h +++ b/icu4c/source/common/ustring.h @@ -23,7 +23,8 @@ #include "utypes.h" /** - * Determine the length of an array of UChar + * Determine the length of an array of UChar. + * * @param s The array of UChars, NULL (U+0000) terminated. * @return The number of UChars in chars, minus the terminator. */ @@ -59,6 +60,7 @@ u_strncat(UChar *dst, /** * Find the first occurrence of a specified character in a ustring. + * * @param s The string to search. * @param c The character to find. * @return A pointer to the first occurrence of c in s, @@ -70,6 +72,7 @@ u_strchr(const UChar *s, /** * Compare two ustrings for bitwise equality. + * * @param s1 A string to compare. * @param s2 A string to compare. * @return 0 if s1 and s2 are bitwise equal; a negative diff --git a/icu4c/source/common/utypes.h b/icu4c/source/common/utypes.h index af4f4017abf..7a29b25cff6 100644 --- a/icu4c/source/common/utypes.h +++ b/icu4c/source/common/utypes.h @@ -95,8 +95,7 @@ typedef uint16_t UChar; /* ICU version number */ /*===========================================================================*/ -/** - * ICU package code version number. +/* * This version number is incremented if and only if the code has changed * in a binary incompatible way. For example, if the algorithm for generating * sort keys has changed, this code version must be incremented. @@ -108,6 +107,11 @@ typedef uint16_t UChar; * for a resource, which consists of this code version number concatenated * with the ResourceBundle data file version number. */ + +/** + * ICU package code version number. + * For internal use only. Please use ResourceBundle::getVersionNumber() + */ #define ICU_VERSION "3" @@ -229,14 +233,17 @@ typedef void* UClassID; /* UErrorCode */ /*===========================================================================*/ -/** Error code to replace exception handling */ +/** Error code to replace exception handling. + * So that the code is compatible with all C++ compilers. + */ enum UErrorCode { U_ERROR_INFO_START = -128, /* Start of information results (semantically successful) */ U_USING_FALLBACK_ERROR = -128, U_USING_DEFAULT_ERROR = -127, U_ERROR_INFO_LIMIT, - U_ZERO_ERROR = 0, /* success */ + /** success */ + U_ZERO_ERROR = 0, U_ILLEGAL_ARGUMENT_ERROR = 1, /* Start of codes indicating failure */ U_MISSING_RESOURCE_ERROR = 2, diff --git a/icu4c/source/i18n/ubrk.h b/icu4c/source/i18n/ubrk.h index 03208426585..5740cfab811 100644 --- a/icu4c/source/i18n/ubrk.h +++ b/icu4c/source/i18n/ubrk.h @@ -16,6 +16,8 @@ #include "utypes.h" /** + * @name BreakIterator C API + * * The BreakIterator C API defines methods for finding the location * of boundaries in text. Pointer to a UBreakIterator maintain a * current position and scan over text returning the index of characters @@ -156,7 +158,11 @@ * . } * */ -/** A text-break iterator */ + +/** + * A text-break iterator. + * For usage in C programs. + */ typedef void* UBreakIterator; /** The possible types of text boundaries. */ @@ -172,7 +178,9 @@ enum UBreakIteratorType { }; typedef enum UBreakIteratorType UBreakIteratorType; -/** Value indicating all text boundaries have been returned. */ +/** Value indicating all text boundaries have been returned. + * + */ #define UBRK_DONE ((UTextOffset) -1) /** diff --git a/icu4c/source/i18n/ucal.h b/icu4c/source/i18n/ucal.h index 4d3aa2b82b2..3b40f1fa8d1 100644 --- a/icu4c/source/i18n/ucal.h +++ b/icu4c/source/i18n/ucal.h @@ -16,6 +16,8 @@ #include "utypes.h" /** + * @name UCalendar C API + * * UCalendar C API is used for converting between a UDate object * and a set of integer fields such as UCAL_YEAR, UCAL_MONTH, * UCAL_DAY, UCAL_HOUR, and so on. @@ -128,7 +130,10 @@ * results in September 7, 1996. * */ -/** A calendar */ + +/** A calendar. + * For usage in C programs. + */ typedef void* UCalendar; /** Possible types of UCalendars */ diff --git a/icu4c/source/i18n/ucol.h b/icu4c/source/i18n/ucol.h index 060eb11bebc..ef7ef6bbb57 100644 --- a/icu4c/source/i18n/ucol.h +++ b/icu4c/source/i18n/ucol.h @@ -16,6 +16,8 @@ #include "utypes.h" /** + * @name Collator C API + * * The C API for Collator performs locale-sensitive * String comparison. You use this class to build * searching and sorting routines for natural language text. @@ -94,7 +96,10 @@ * @see UCollationStrength * @see UCollationElements */ -/** A collator */ + + /** A collator. + * For usage in C programs. + */ typedef void* UCollator; /** @@ -194,6 +199,8 @@ typedef enum UCollationStrength UCollationStrength; ================================================= ===============================================*/ /** + * @name Unicode normalization API + * * u_normalize transforms Unicode text into an equivalent composed or * decomposed form, allowing for easier sorting and searching of text. * u_normalize supports the standard normalization forms described in @@ -541,7 +548,9 @@ ucol_keyHashCode( const uint8_t* key, int32_t length); -/** The UCollationElements struct */ +/** The UCollationElements struct. + * For usage in C programs. + */ struct UCollationElements; typedef struct UCollationElements UCollationElements; /** @@ -592,8 +601,10 @@ typedef struct UCollationElements UCollationElements; * * @see Collator */ + /** * Open the collation elements for a string. + * * @param coll The collator containing the desired collation rules. * @param text The text to iterate over. * @param textLength The number of characters in text, or -1 if null-terminated @@ -605,16 +616,18 @@ ucol_openElements( const UCollator *coll, int32_t textLength, UErrorCode *status); -/** Bit mask for primary collation strength */ +/* Bit mask for primary collation strength. */ #define UCOL_PRIMARYMASK 0xFFFF0000 -/** Bit mask for secondary collation strength */ +/* Bit mask for secondary collation strength. */ #define UCOL_SECONDARYMASK 0x0000FF00 -/** Bit mask for tertiary collation strength */ +/* Bit mask for tertiary collation strength. */ #define UCOL_TERTIARYMASK 0x000000FF -/** This indicates the last element in a UCollationElements has been consumed. */ +/** This indicates the last element in a UCollationElements has been consumed. + * + */ #define UCOL_NULLORDER 0xFFFFFFFF /** diff --git a/icu4c/source/i18n/udat.h b/icu4c/source/i18n/udat.h index 4a8a1085ef8..5f3dcfd3081 100644 --- a/icu4c/source/i18n/udat.h +++ b/icu4c/source/i18n/udat.h @@ -18,6 +18,7 @@ #include "ucal.h" #include "unum.h" /** + * @name Date Format C API * Date Format C API consists of functions that convert dates and * times from their internal representations to textual form and back again in a * language-independent manner. Converting from the internal representation (milliseconds @@ -96,7 +97,10 @@ * on the screen. * */ -/** A date formatter */ + +/** A date formatter. + * For usage in C programs. + */ typedef void* UDateFormat; /** The possible date/time format styles */ @@ -388,7 +392,9 @@ enum UDateFormatSymbolType { }; typedef enum UDateFormatSymbolType UDateFormatSymbolType; -/** Date format symbols */ +/** Date format symbols. + * For usage in C programs. + */ struct UDateFormatSymbols; typedef struct UDateFormatSymbols UDateFormatSymbols; diff --git a/icu4c/source/i18n/unum.h b/icu4c/source/i18n/unum.h index a915b45c3cf..67f15daf4a2 100644 --- a/icu4c/source/i18n/unum.h +++ b/icu4c/source/i18n/unum.h @@ -22,6 +22,8 @@ #include "umisc.h" /** + * @name Number Format C API + * * Number Format C API Provides functions for * formatting and parsing a number. Also provides methods for * determining which locales have number formats, and what their names @@ -103,7 +105,10 @@ * locale like the currency symbol, the grouping seperator , monetary seperator * etc by making use of functions unum_setSymbols() and unum_getSymbols(). */ -/** A number formatter */ + +/** A number formatter. + * For usage in C programs. + */ typedef void* UNumberFormat; /** The possible number format styles. */ @@ -493,7 +498,7 @@ unum_toPattern( const UNumberFormat* fmt, int32_t resultLength, UErrorCode* status); -/** The maximum size for a textual number format symbol */ +/* The maximum size for a textual number format symbol. */ #define UNFSYMBOLSMAXSIZE 10 /** The UNumberFormatSymbols struct */ diff --git a/icu4c/source/tools/ctestfw/ctest.h b/icu4c/source/tools/ctestfw/ctest.h index 4b58717dfa7..b26d09d864c 100644 --- a/icu4c/source/tools/ctestfw/ctest.h +++ b/icu4c/source/tools/ctestfw/ctest.h @@ -59,28 +59,35 @@ typedef void (*TestFunctionPtr)(); typedef struct TestNode TestNode; /** - * Count of errors from all tests. May be reset. + * Count of errors from all tests. + * May be reset. */ T_CTEST_EXPORT_API extern int ERROR_COUNT; /** - * Set this to zero to disable log_verbose() messages, otherwise - * nonzero to see log_verbose() messages. + * Set this to zero to disable log_verbose() messages. + * Otherwise nonzero to see log_verbose() messages. + * */ T_CTEST_EXPORT_API extern int VERBOSITY; + /** - * Set this to zero to disable log_verbose() messages, otherwise - * nonzero to see log_verbose() messages. + * Set this to zero to disable log_verbose() messages. + * Otherwise nonzero to see log_verbose() messages. + * */ T_CTEST_EXPORT_API extern int ERR_MSG; + /** * Show the names of all nodes. + * * @param root Subtree of tests. */ T_CTEST_API void showTests ( const TestNode *root); /** * Run a subtree of tests. + * * @param root Subtree of tests. */ T_CTEST_API void runTests ( const TestNode* root); @@ -101,7 +108,8 @@ T_CTEST_API void addTest ( TestNode** root, const char *path); /** - * Retreive a specific subtest (subtree) + * Retreive a specific subtest. (subtree). + * * @param root Pointer to the root. * @param path Path relative to the root, Ex. '/a/b' * @return The subtest, or NULL on failure.