From 4bd6bbcee20a35bb7922a9ee59f664af4817ee6d Mon Sep 17 00:00:00 2001
From: Hugo van der Merwe <17109322+hugovdm@users.noreply.github.com>
Date: Tue, 14 Apr 2020 20:59:41 +0200
Subject: [PATCH] Improve documentation comments.

---
 icu4c/source/i18n/unitsdata.cpp | 12 +++---------
 icu4c/source/i18n/unitsdata.h   | 24 +++++++++++++++---------
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/icu4c/source/i18n/unitsdata.cpp b/icu4c/source/i18n/unitsdata.cpp
index 3e285b65bd6..27990386e7d 100644
--- a/icu4c/source/i18n/unitsdata.cpp
+++ b/icu4c/source/i18n/unitsdata.cpp
@@ -20,15 +20,7 @@ namespace {
 /**
  * A ResourceSink that collects conversion rate information.
  *
- * This class is for use by ures_getAllItemsWithFallback. Example code for
- * collecting conversion info for "mile" and "foot" into conversionInfoOutput:
- *
- *     UErrorCode status = U_ZERO_ERROR;
- *     ures_getByKey(unitsBundle, "convertUnits", &fillIn, &status);
- *     MaybeStackVector<ConversionRateInfo> conversionInfoOutput;
- *     ConversionRateDataSink convertSink(conversionInfoOutput);
- *     ures_getAllItemsWithFallback(fillIn, "mile", convertSink, status);
- *     ures_getAllItemsWithFallback(fillIn, "foot", convertSink, status);
+ * This class is for use by ures_getAllItemsWithFallback.
  */
 class ConversionRateDataSink : public ResourceSink {
   public:
@@ -55,6 +47,8 @@ class ConversionRateDataSink : public ResourceSink {
     void put(const char *source, ResourceValue &value, UBool /*noFallback*/, UErrorCode &status) {
         if (U_FAILURE(status)) return;
         if (uprv_strcmp(source, "convertUnits") != 0) {
+            // This is very strict, however it is the cheapest way to be sure
+            // that with `value`, we're looking at the convertUnits table.
             status = U_ILLEGAL_ARGUMENT_ERROR;
             return;
         }
diff --git a/icu4c/source/i18n/unitsdata.h b/icu4c/source/i18n/unitsdata.h
index 87e49a8ec6f..5bba426862d 100644
--- a/icu4c/source/i18n/unitsdata.h
+++ b/icu4c/source/i18n/unitsdata.h
@@ -15,11 +15,15 @@
 
 U_NAMESPACE_BEGIN
 
-// Encapsulates "convertUnits" information from units resources, specifying how
-// to convert from one unit to another.
-//
-// Information in this class is still in the form of strings: symbolic constants
-// need to be interpreted.
+/**
+ * Encapsulates "convertUnits" information from units resources, specifying how
+ * to convert from one unit to another.
+ *
+ * Information in this class is still in the form of strings: symbolic constants
+ * need to be interpreted. Rationale: symbols can cancel out for higher
+ * precision conversion - going from feet to inches should cancel out the
+ * `ft_to_m` constant.
+ */
 class U_I18N_API ConversionRateInfo {
   public:
     ConversionRateInfo(){};
@@ -45,11 +49,13 @@ class U_I18N_API ConversionRateInfo {
 MaybeStackVector<ConversionRateInfo> U_I18N_API getAllConversionRates(UErrorCode &status);
 
 /**
- * Collects and returns ConversionRateInfo needed for conversions for a set of
- * units.
+ * Temporary backward-compatibility function.
  *
- * @param units The units for which to load conversion data.
- * @param status Receives status.
+ * TODO(hugovdm): ensure this gets removed. Currently
+ * https://github.com/sffc/icu/pull/32 is making use of it.
+ *
+ * @param units Ignored.
+ * @return the result of getAllConversionRates.
  */
 MaybeStackVector<ConversionRateInfo>
     U_I18N_API getConversionRatesInfo(const MaybeStackVector<MeasureUnit> &units, UErrorCode &status);
-- 
2.50.1