ICU-12042 better API docs

X-SVN-Rev: 38161

diff --git a/icu4c/source/common/unicode/ures.h b/icu4c/source/common/unicode/ures.h
index 8ceb92d104549048aa765537b9dc2063a4681569..03a01be22f50b2e6953dbc82e2434945d923add4 100644 (file)
--- a/icu4c/source/common/unicode/ures.h
+++ b/icu4c/source/common/unicode/ures.h
@@ -789,14 +789,14 @@ ures_getUTF8StringByKey(const UResourceBundle *resB,
 
 U_NAMESPACE_BEGIN
 /**
- * returns a string from a string resource type
+ * Returns the string value from a string resource bundle.
  *
- * @param resB    a resource
+ * @param resB    a resource, should have type URES_STRING
  * @param status: fills in the outgoing error code
  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
  *                could be a non-failing error 
  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
- * @return        a UnicodeString object. If there is an error, string is bogus
+ * @return The string value, or a bogus string if there is a failure UErrorCode.
  * @stable ICU 2.0
  */
 inline UnicodeString
@@ -813,13 +813,15 @@ ures_getUnicodeString(const UResourceBundle *resB, UErrorCode* status) {
 }
 
 /**
- * Returns the next string in a resource or NULL if there are no more resources 
- * to iterate over. 
+ * Returns the next string in a resource, or an empty string if there are no more resources
+ * to iterate over.
+ * Use ures_getNextString() instead to distinguish between
+ * the end of the iteration and a real empty string value.
  *
  * @param resB              a resource
  * @param key               fill in for key associated with this string
  * @param status            fills in the outgoing error code
- * @return an UnicodeString object.
+ * @return The string value, or a bogus string if there is a failure UErrorCode.
  * @stable ICU 2.0
  */
 inline UnicodeString
@@ -836,12 +838,12 @@ ures_getNextUnicodeString(UResourceBundle *resB, const char ** key, UErrorCode*
 }
 
 /**
- * Returns the string in a given resource at the specified index.
+ * Returns the string in a given resource array or table at the specified index.
  *
  * @param resB              a resource
  * @param indexS            an index to the wanted string.
  * @param status            fills in the outgoing error code
- * @return                  an UnicodeString object. If there is an error, string is bogus
+ * @return The string value, or a bogus string if there is a failure UErrorCode.
  * @stable ICU 2.0
  */
 inline UnicodeString
@@ -858,13 +860,13 @@ ures_getUnicodeStringByIndex(const UResourceBundle *resB, int32_t indexS, UError
 }
 
 /**
- * Returns a string in a resource that has a given key. This procedure works only with table
- * resources. 
+ * Returns a string in a resource that has a given key.
+ * This procedure works only with table resources.
  *
  * @param resB              a resource
  * @param key               a key associated with the wanted string
  * @param status            fills in the outgoing error code
- * @return                  an UnicodeString object. If there is an error, string is bogus
+ * @return The string value, or a bogus string if there is a failure UErrorCode.
  * @stable ICU 2.0
  */
 inline UnicodeString