From 57fd3d7ef98188cfcba3d36a374d6094388d8bc5 Mon Sep 17 00:00:00 2001
From: Markus Scherer <markus.icu@gmail.com>
Date: Thu, 20 Sep 2012 05:37:31 +0000
Subject: [PATCH] ICU-9589 document that the so-called UCA rules are not
 normally useful and can be removed from the data

X-SVN-Rev: 32412
---
 icu4c/source/i18n/unicode/tblcoll.h |  4 ++++
 icu4c/source/i18n/unicode/ucol.h    | 20 +++++++++++++++++---
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/icu4c/source/i18n/unicode/tblcoll.h b/icu4c/source/i18n/unicode/tblcoll.h
index afc7312eba7..235a3b2018a 100644
--- a/icu4c/source/i18n/unicode/tblcoll.h
+++ b/icu4c/source/i18n/unicode/tblcoll.h
@@ -457,9 +457,13 @@ public:
     /**
      * Returns current rules. Delta defines whether full rules are returned or
      * just the tailoring.
+     *
+     * getRules(void) should normally be used instead.
+     * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales
      * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES.
      * @param buffer UnicodeString to store the result rules
      * @stable ICU 2.2
+     * @see UCOL_FULL_RULES
      */
     void getRules(UColRuleOption delta, UnicodeString &buffer);
 
diff --git a/icu4c/source/i18n/unicode/ucol.h b/icu4c/source/i18n/unicode/ucol.h
index f8189d10d83..8580cbe5823 100644
--- a/icu4c/source/i18n/unicode/ucol.h
+++ b/icu4c/source/i18n/unicode/ucol.h
@@ -334,9 +334,19 @@ typedef enum {
  *  @stable ICU 2.0
  */
 typedef enum {
-  /** Retrieve tailoring only */
+  /**
+   * Retrieves the tailoring rules only.
+   * Same as calling the version of getRules() without UColRuleOption.
+   * @stable ICU 2.0
+   */
   UCOL_TAILORING_ONLY, 
-  /** Retrieve UCA rules and tailoring */
+  /**
+   * Retrieves the "UCA rules" concatenated with the tailoring rules.
+   * The "UCA rules" are an <i>approximation</i> of the root collator's sort order.
+   * They are almost never used or useful at runtime and can be removed from the data.
+   * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales
+   * @stable ICU 2.0
+   */
   UCOL_FULL_RULES 
 } UColRuleOption ;
 
@@ -1193,12 +1203,16 @@ ucol_safeClone(const UCollator *coll,
  * Returns current rules. Delta defines whether full rules are returned or just the tailoring. 
  * Returns number of UChars needed to store rules. If buffer is NULL or bufferLen is not enough 
  * to store rules, will store up to available space.
+ *
+ * ucol_getRules() should normally be used instead.
+ * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales
  * @param coll collator to get the rules from
  * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES. 
  * @param buffer buffer to store the result in. If NULL, you'll get no rules.
- * @param bufferLen lenght of buffer to store rules in. If less then needed you'll get only the part that fits in.
+ * @param bufferLen length of buffer to store rules in. If less than needed you'll get only the part that fits in.
  * @return current rules
  * @stable ICU 2.0
+ * @see UCOL_FULL_RULES
  */
 U_STABLE int32_t U_EXPORT2 
 ucol_getRulesEx(const UCollator *coll, UColRuleOption delta, UChar *buffer, int32_t bufferLen);