From 64835de2571962bccdb1de8f5a6ca9e0946e6dd2 Mon Sep 17 00:00:00 2001 From: "Steven R. Loomis" Date: Tue, 19 Jan 2010 23:39:42 +0000 Subject: [PATCH] ICU-7353 docs fixup X-SVN-Rev: 27339 --- icu4c/source/Doxyfile.in | 11 ++-- icu4c/source/common/unicode/icuplug.h | 62 +++++++++++++---------- icu4c/source/common/unicode/platform.h.in | 4 +- icu4c/source/common/unicode/ubidi.h | 8 ++- icu4c/source/common/unicode/ubrk.h | 6 +-- icu4c/source/common/unicode/uchar.h | 2 +- icu4c/source/common/unicode/uidna.h | 8 ++- icu4c/source/common/unicode/unistr.h | 2 +- icu4c/source/common/unicode/uobject.h | 7 ++- icu4c/source/common/unicode/utypes.h | 22 ++++---- icu4c/source/i18n/unicode/locdspnm.h | 4 +- icu4c/source/i18n/unicode/uldnames.h | 1 + 12 files changed, 75 insertions(+), 62 deletions(-) diff --git a/icu4c/source/Doxyfile.in b/icu4c/source/Doxyfile.in index 600c9daccb1..771b99391ff 100644 --- a/icu4c/source/Doxyfile.in +++ b/icu4c/source/Doxyfile.in @@ -1,7 +1,7 @@ # Doxyfile 1.3.7 # ******************************************************************** # * COPYRIGHT: -# * Copyright (c) 2004-2009, International Business Machines Corporation +# * Copyright (c) 2004-2010, International Business Machines Corporation # * and others. All Rights Reserved. # ******************************************************************** @@ -9,11 +9,12 @@ # Project related configuration options #--------------------------------------------------------------------------- PROJECT_NAME = "ICU @VERSION@" -PROJECT_NUMBER = +PROJECT_NUMBER = @VERSION@ OUTPUT_DIRECTORY = doc CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English -USE_WINDOWS_ENCODING = YES +#USE_WINDOWS_ENCODING = YES +DOXYFILE_ENCODING = UTF-8 BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ABBREVIATE_BRIEF = @@ -25,7 +26,7 @@ STRIP_FROM_INC_PATH = SHORT_NAMES = NO JAVADOC_AUTOBRIEF = YES MULTILINE_CPP_IS_BRIEF = NO -DETAILS_AT_TOP = NO +#DETAILS_AT_TOP = NO INHERIT_DOCS = YES DISTRIBUTE_GROUP_DOC = YES TAB_SIZE = 8 @@ -215,9 +216,11 @@ TEMPLATE_RELATIONS = NO INCLUDE_GRAPH = YES INCLUDED_BY_GRAPH = YES CALL_GRAPH = NO +CALLER_GRAPH = NO GRAPHICAL_HIERARCHY = YES DOT_IMAGE_FORMAT = png DOT_PATH = +#DOT_FONTNAME = FreeSans DOTFILE_DIRS = MAX_DOT_GRAPH_WIDTH = 1024 MAX_DOT_GRAPH_HEIGHT = 1024 diff --git a/icu4c/source/common/unicode/icuplug.h b/icu4c/source/common/unicode/icuplug.h index 35d8ea46209..be886f430ae 100644 --- a/icu4c/source/common/unicode/icuplug.h +++ b/icu4c/source/common/unicode/icuplug.h @@ -70,10 +70,10 @@ *

Implementing a Plugin

* \code * U_CAPI UPlugTokenReturn U_EXPORT2 - * myPlugin (UPlugData *data, UPlugReason reason, UErrorCode *status) { + * myPlugin (UPlugData *plug, UPlugReason reason, UErrorCode *status) { * if(reason==UPLUG_REASON_QUERY) { - * uplug_setPlugName(data, "Simple Plugin"); - * uplug_setPlugLevel(data, UPLUG_LEVEL_HIGH); + * uplug_setPlugName(plug, "Simple Plugin"); + * uplug_setPlugLevel(plug, UPLUG_LEVEL_HIGH); * } else if(reason==UPLUG_REASON_LOAD) { * ... Set up some ICU things here.... * } else if(reason==UPLUG_REASON_UNLOAD) { @@ -111,6 +111,7 @@ /* === Basic types === */ /** + * @{ * Opaque structure passed to/from a plugin. * use the APIs to access it. * @internal ICU 4.4 Technology Preview @@ -119,6 +120,8 @@ struct UPlugData; typedef struct UPlugData UPlugData; +/** @} */ + /** * Random Token to identify a valid ICU plugin. Plugins must return this * from the entrypoint. @@ -170,13 +173,13 @@ typedef enum { /** * Entrypoint for an ICU plugin. - * @param data the UPlugData handle. + * @param plug the UPlugData handle. * @param status the plugin's extended status code. * @return A valid plugin must return UPLUG_TOKEN * @internal ICU 4.4 Technology Preview */ typedef UPlugTokenReturn (U_EXPORT2 UPlugEntrypoint) ( - UPlugData *data, + UPlugData *plug, UPlugReason reason, UErrorCode *status); @@ -186,28 +189,30 @@ typedef UPlugTokenReturn (U_EXPORT2 UPlugEntrypoint) ( * Request that this plugin not be unloaded at cleanup time. * This is appropriate for plugins which cannot be cleaned up. * @see u_cleanup() + * @param plug plugin + * @param dontUnload set true if this plugin can't be unloaded * @internal ICU 4.4 Technology Preview */ U_CAPI void U_EXPORT2 -uplug_setPlugNoUnload(UPlugData *data, UBool dontUnload); +uplug_setPlugNoUnload(UPlugData *plug, UBool dontUnload); /** * Set the level of this plugin. - * @param data plugin data handle + * @param plug plugin data handle * @param level the level of this plugin * @internal ICU 4.4 Technology Preview */ U_CAPI void U_EXPORT2 -uplug_setPlugLevel(UPlugData *data, UPlugLevel level); +uplug_setPlugLevel(UPlugData *plug, UPlugLevel level); /** * Get the level of this plugin. - * @param data plugin data handle + * @param plug plugin data handle * @return the level of this plugin * @internal ICU 4.4 Technology Preview */ U_CAPI UPlugLevel U_EXPORT2 -uplug_getPlugLevel(UPlugData *data); +uplug_getPlugLevel(UPlugData *plug); /** * Get the lowest level of plug which can currently load. @@ -229,78 +234,79 @@ uplug_getPlugLoadStatus(UPlugData *plug); /** * Set the human-readable name of this plugin. - * @param data plugin data handle + * @param plug plugin data handle * @param name the name of this plugin. The first UPLUG_NAME_MAX characters willi be copied into a new buffer. * @internal ICU 4.4 Technology Preview */ U_CAPI void U_EXPORT2 -uplug_setPlugName(UPlugData *data, const char *name); +uplug_setPlugName(UPlugData *plug, const char *name); /** * Get the human-readable name of this plugin. - * @param data plugin data handle + * @param plug plugin data handle * @return the name of this plugin * @internal ICU 4.4 Technology Preview */ U_CAPI const char * U_EXPORT2 -uplug_getPlugName(UPlugData *data); +uplug_getPlugName(UPlugData *plug); /** * Return the symbol name for this plugin, if known. - * @param data plugin data handle + * @param plug plugin data handle * @return the symbol name, or NULL * @internal ICU 4.4 Technology Preview */ U_CAPI const char * U_EXPORT2 -uplug_getSymbolName(UPlugData *data); +uplug_getSymbolName(UPlugData *plug); /** * Return the library name for this plugin, if known. - * @param data plugin data handle + * @param plug plugin data handle + * @param status error code * @return the library name, or NULL * @internal ICU 4.4 Technology Preview */ U_CAPI const char * U_EXPORT2 -uplug_getLibraryName(UPlugData *data, UErrorCode *status); +uplug_getLibraryName(UPlugData *plug, UErrorCode *status); /** * Return the library used for this plugin, if known. * Plugins could use this to load data out of their - * @param data plugin data handle + * @param plug plugin data handle * @return the library, or NULL * @internal ICU 4.4 Technology Preview */ U_CAPI void * U_EXPORT2 -uplug_getLibrary(UPlugData *data); +uplug_getLibrary(UPlugData *plug); /** * Return the plugin-specific context data. - * @param data plugin data handle + * @param plug plugin data handle * @return the context, or NULL if not set * @internal ICU 4.4 Technology Preview */ U_CAPI void * U_EXPORT2 -uplug_getContext(UPlugData *data); +uplug_getContext(UPlugData *plug); /** * Set the plugin-specific context data. - * @param data plugin data handle + * @param plug plugin data handle * @param context new context to set * @internal ICU 4.4 Technology Preview */ U_CAPI void U_EXPORT2 -uplug_setContext(UPlugData *data, void *context); +uplug_setContext(UPlugData *plug, void *context); /** * Get the configuration string, if available. * The string is in the platform default codepage. - * @param data plugin data handle + * @param plug plugin data handle * @return configuration string, or else null. * @internal ICU 4.4 Technology Preview */ U_CAPI const char * U_EXPORT2 -uplug_getConfiguration(UPlugData *data); +uplug_getConfiguration(UPlugData *plug); /** * Return all currently installed plugins, from newest to oldest @@ -314,7 +320,7 @@ uplug_getConfiguration(UPlugData *data); * Not thread safe- do not call while plugs are added or removed. * @param prior pass in 'NULL' to get the first (most recent) plug, * otherwise pass the value returned on a prior call to uplug_nextPlug - * @param return the next oldest plugin, or NULL if no more. + * @return the next oldest plugin, or NULL if no more. * @internal ICU 4.4 Technology Preview */ U_CAPI UPlugData* U_EXPORT2 @@ -352,7 +358,7 @@ uplug_loadPlugFromLibrary(const char *libName, const char *sym, const char *conf /** * Remove a plugin. * Will request the plugin to be unloaded, and close the library if needed - * @param data plugin handle to close + * @param plug plugin handle to close * @param status error result * @internal ICU 4.4 Technology Preview */ diff --git a/icu4c/source/common/unicode/platform.h.in b/icu4c/source/common/unicode/platform.h.in index 96fcca359a9..9331045a682 100644 --- a/icu4c/source/common/unicode/platform.h.in +++ b/icu4c/source/common/unicode/platform.h.in @@ -33,7 +33,7 @@ # error Do not include unicode/uvernum.h before #including unicode/platform.h. Instead of unicode/uvernum.h, #include unicode/uversion.h #endif -/* Determine wheter to enable auto cleanup of libraries. */ +/** Determine wheter to enable auto cleanup of libraries. */ #ifndef UCLN_NO_AUTO_CLEANUP #define UCLN_NO_AUTO_CLEANUP @UCLN_NO_AUTO_CLEANUP@ #endif @@ -41,7 +41,7 @@ /* Need platform.h when using CYGWINMSVC to get definitions above. Ignore everything else. */ #ifndef CYGWINMSVC -/* Define the platform we're on. */ +/** Define the platform we're on. */ #ifndef @platform@ #define @platform@ #endif diff --git a/icu4c/source/common/unicode/ubidi.h b/icu4c/source/common/unicode/ubidi.h index 09b03039fcf..43cbd8ec99b 100644 --- a/icu4c/source/common/unicode/ubidi.h +++ b/icu4c/source/common/unicode/ubidi.h @@ -1,7 +1,7 @@ /* ****************************************************************************** * -* Copyright (C) 1999-2009, International Business Machines +* Copyright (C) 1999-2010, International Business Machines * Corporation and others. All Rights Reserved. * ****************************************************************************** @@ -811,12 +811,10 @@ typedef enum UBiDiReorderingMode { * *
  • When the reordering mode is set to * #UBIDI_REORDER_INVERSE_FOR_NUMBERS_SPECIAL, the Logical to Visual - * Bidi algorithm used in Windows XP is used as an approximation of an - * "inverse Bidi" algorithm. + * Bidi algorithm used in Windows XP is used as an approximation of an "inverse Bidi" algorithm. *
    * For example, an LTR paragraph with the content "abc FED123" (where - * upper case represents RTL characters) will be transformed to - * "abc 123DEF.
    • + * upper case represents RTL characters) will be transformed to "abc 123DEF." * * *

    In all the reordering modes specifying an "inverse Bidi" algorithm diff --git a/icu4c/source/common/unicode/ubrk.h b/icu4c/source/common/unicode/ubrk.h index da79aa8ef18..e5c02970162 100644 --- a/icu4c/source/common/unicode/ubrk.h +++ b/icu4c/source/common/unicode/ubrk.h @@ -1,6 +1,6 @@ /* ****************************************************************************** -* Copyright (C) 1996-2009, International Business Machines Corporation and others. +* Copyright (C) 1996-2010, International Business Machines Corporation and others. * All Rights Reserved. ****************************************************************************** */ @@ -77,10 +77,10 @@ * object oriented C++ API with equivalent functionality is defined in the * file brkiter.h. *

    - * Code snippits illustrating the use of the Break Iterator APIs + * Code snippets illustrating the use of the Break Iterator APIs * are available in the ICU User Guide, * http://icu-project.org/userguide/boundaryAnalysis.html - * and in the sample program icu/source/samples/break/break.cpp" + * and in the sample program icu/source/samples/break/break.cpp */ /** The possible types of text boundaries. @stable ICU 2.0 */ diff --git a/icu4c/source/common/unicode/uchar.h b/icu4c/source/common/unicode/uchar.h index 31fb5013a40..c528575abb6 100644 --- a/icu4c/source/common/unicode/uchar.h +++ b/icu4c/source/common/unicode/uchar.h @@ -351,7 +351,7 @@ typedef enum UProperty { Unicode normalization and combining character sequences. They have ccc=0 and do not occur in non-initial position of the canonical decomposition of any character - (like " in NFD(a-umlaut) and a Jamo T in an NFD(Hangul LVT)). + (like a-umlaut in NFD and a Jamo T in an NFD(Hangul LVT)). ICU uses this property for segmenting a string for generating a set of canonically equivalent strings, e.g. for canonical closure while processing collation tailoring rules. diff --git a/icu4c/source/common/unicode/uidna.h b/icu4c/source/common/unicode/uidna.h index 52aa6e9104e..edab2d0dcaf 100644 --- a/icu4c/source/common/unicode/uidna.h +++ b/icu4c/source/common/unicode/uidna.h @@ -1,7 +1,7 @@ /* ******************************************************************************* * - * Copyright (C) 2003-2007, International Business Machines + * Copyright (C) 2003-2010, International Business Machines * Corporation and others. All Rights Reserved. * ******************************************************************************* @@ -76,8 +76,7 @@ * This function implements the ToASCII operation as defined in the IDNA RFC. * This operation is done on single labels before sending it to something that expects * ASCII names. A label is an individual part of a domain name. Labels are usually - * separated by dots; e.g." "www.example.com" is composed of 3 labels - * "www","example", and "com". + * separated by dots; e.g." "www.example.com" is composed of 3 labels "www","example", and "com". * * * @param src Input UChar array containing label in Unicode. @@ -123,8 +122,7 @@ uidna_toASCII(const UChar* src, int32_t srcLength, * This function implements the ToUnicode operation as defined in the IDNA RFC. * This operation is done on single labels before sending it to something that expects * Unicode names. A label is an individual part of a domain name. Labels are usually - * separated by dots; for e.g." "www.example.com" is composed of 3 labels - * "www","example", and "com". + * separated by dots; for e.g." "www.example.com" is composed of 3 labels "www","example", and "com". * * @param src Input UChar array containing ASCII (ACE encoded) label. * @param srcLength Number of UChars in src, or -1 if NUL-terminated. diff --git a/icu4c/source/common/unicode/unistr.h b/icu4c/source/common/unicode/unistr.h index b3b2898c7e5..87440c76ba5 100644 --- a/icu4c/source/common/unicode/unistr.h +++ b/icu4c/source/common/unicode/unistr.h @@ -1613,7 +1613,7 @@ public: * Unpaired surrogates are replaced with U+FFFD. * Calls toUTF8(). * - * @param A standard string (or a compatible object) + * @param result A standard string (or a compatible object) * to which the UTF-8 version of the string is appended. * @return The string object. * @draft ICU 4.2 diff --git a/icu4c/source/common/unicode/uobject.h b/icu4c/source/common/unicode/uobject.h index 4a701da1fc2..d1575602ed5 100644 --- a/icu4c/source/common/unicode/uobject.h +++ b/icu4c/source/common/unicode/uobject.h @@ -1,7 +1,7 @@ /* ****************************************************************************** * -* Copyright (C) 2002-2009, International Business Machines +* Copyright (C) 2002-2010, International Business Machines * Corporation and others. All Rights Reserved. * ****************************************************************************** @@ -64,9 +64,10 @@ U_NAMESPACE_BEGIN #endif /** + * @{ * \def U_NO_THROW * Define this to define the throw() specification so - certain functions do not throw any exceptions + * certain functions do not throw any exceptions * * UMemory operator new methods should have the throw() specification * appended to them, so that the compiler adds the additional NULL check @@ -80,6 +81,8 @@ U_NAMESPACE_BEGIN #define U_NO_THROW throw() #endif +/** @} */ + /** * UMemory is the common ICU base class. * All other ICU C++ classes are derived from UMemory (starting with ICU 2.4). diff --git a/icu4c/source/common/unicode/utypes.h b/icu4c/source/common/unicode/utypes.h index eb68aa1c0f1..7ea6c9c8182 100644 --- a/icu4c/source/common/unicode/utypes.h +++ b/icu4c/source/common/unicode/utypes.h @@ -38,6 +38,16 @@ #include "unicode/uversion.h" #include "unicode/uconfig.h" +/*! + * \file + * \brief Basic definitions for ICU, for both C and C++ APIs + * + * This file defines basic types, constants, and enumerations directly or + * indirectly by including other header files, especially utf.h for the + * basic character and string definitions and umachine.h for consistent + * integer and other types. + */ + #ifdef XP_CPLUSPLUS # ifndef U_SHOW_CPLUSPLUS_API @@ -48,6 +58,7 @@ # define U_SHOW_CPLUSPLUS_API 0 #endif +/** @{ API visibility control */ /** * \def U_HIDE_DRAFT_API @@ -80,15 +91,8 @@ #include "unicode/usystem.h" #endif -/*! - * \file - * \brief Basic definitions for ICU, for both C and C++ APIs - * - * This file defines basic types, constants, and enumerations directly or - * indirectly by including other header files, especially utf.h for the - * basic character and string definitions and umachine.h for consistent - * integer and other types. - */ +/** @} */ + /*===========================================================================*/ /* char Character set family */ diff --git a/icu4c/source/i18n/unicode/locdspnm.h b/icu4c/source/i18n/unicode/locdspnm.h index b68ad1677a1..8d8a488bf52 100644 --- a/icu4c/source/i18n/unicode/locdspnm.h +++ b/icu4c/source/i18n/unicode/locdspnm.h @@ -38,8 +38,8 @@ public: virtual ~LocaleDisplayNames(); /** - * Convenience overload of {@link #createInstance(locale, - * UDialectHandling)} that specifies STANDARD dialect handling. + * Convenience overload of {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)} + * that specifies STANDARD dialect handling. * @param locale the display locale * @return a LocaleDisplayNames instance * @draft ICU 4.4 diff --git a/icu4c/source/i18n/unicode/uldnames.h b/icu4c/source/i18n/unicode/uldnames.h index a9913e24197..1e251ed795e 100644 --- a/icu4c/source/i18n/unicode/uldnames.h +++ b/icu4c/source/i18n/unicode/uldnames.h @@ -58,6 +58,7 @@ typedef struct ULocaleDisplayNames ULocaleDisplayNames; * @param locale the display locale * @param dialectHandling how to select names for locales * @return a ULocaleDisplayNames instance + * @param pErrorCode the status code * @draft ICU 4.4 */ U_DRAFT ULocaleDisplayNames * U_EXPORT2