ICU-8134 improve API docs for getBaseName() & setKeywordValue()

X-SVN-Rev: 33814

diff --git a/icu4c/source/common/unicode/locid.h b/icu4c/source/common/unicode/locid.h
index c406183b105fd4d9490cfe3c88a5a541018c0937..904599ab795f21572809b2d6e9e265473ada05e2 100644 (file)
--- a/icu4c/source/common/unicode/locid.h
+++ b/icu4c/source/common/unicode/locid.h
@@ -421,7 +421,7 @@ public:
     inline const char * getName() const;
 
     /**
-     * Returns the programmatic name of the entire locale as getName would return,
+     * Returns the programmatic name of the entire locale as getName() would return,
      * but without keywords.
      * @return      A pointer to "name".
      * @see getName
@@ -454,7 +454,10 @@ public:
     int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const;
 
     /**
-     * Sets the value for a keyword.
+     * Sets or removes the value for a keyword.
+     *
+     * For removing all keywords, use getBaseName(),
+     * and construct a new Locale if it differs from getName().
      *
      * @param keywordName name of the keyword to be set. Case insensitive.
      * @param keywordValue value of the keyword to be set. If 0-length or

diff --git a/icu4c/source/common/unicode/uloc.h b/icu4c/source/common/unicode/uloc.h
index a8b59fb6d429779ed616f9e6ff19d5a740536e1d..28ab902b522293b3320e9e9d07eadf1391658aeb 100644 (file)
--- a/icu4c/source/common/unicode/uloc.h
+++ b/icu4c/source/common/unicode/uloc.h
@@ -800,12 +800,15 @@ uloc_getParent(const char*    localeID,
 
 
 /**
- * Gets the full name for the specified locale.
+ * Gets the full name for the specified locale, like uloc_getName(),
+ * but without keywords.
+ *
  * Note: This has the effect of 'canonicalizing' the string to
  * a certain extent. Upper and lower case are set as needed,
  * and if the components were in 'POSIX' format they are changed to
  * ICU format.  It does NOT map aliased names in any way.
  * See the top of this header file.
+ *
  * This API strips off the keyword part, so "de_DE\@collation=phonebook" 
  * will become "de_DE". 
  * This API supports preflighting.
@@ -856,13 +859,16 @@ uloc_getKeywordValue(const char* localeID,
 
 
 /**
- * Set the value of the specified keyword.
+ * Sets or removes the value of the specified keyword.
+ *
+ * For removing all keywords, use uloc_getBaseName().
+ *
  * NOTE: Unlike almost every other ICU function which takes a
  * buffer, this function will NOT truncate the output text. If a
  * BUFFER_OVERFLOW_ERROR is received, it means that the original
  * buffer is untouched. This is done to prevent incorrect or possibly
  * even malformed locales from being generated and used.
- * 
+ *
  * @param keywordName name of the keyword to be set. Case insensitive.
  * @param keywordValue value of the keyword to be set. If 0-length or
  *  NULL, will result in the keyword being removed. No error is given if