Extended documentation on UKM enum configuration.

Change-Id: Ibc22fe9f59e7a5cd79b2e4a3a3de08f445c15812
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1489179
Auto-Submit: Brian White <bcwhite@chromium.org>
Commit-Queue: Brian White <bcwhite@chromium.org>
Reviewed-by: Robert Kaplow <rkaplow@chromium.org>
Cr-Commit-Position: refs/heads/master@{#638599}

services/metrics/ukm_api.md

@@ -64,10 +64,8 @@ Supported statistic types are:
     for the values which are 1, 5, 10, 25, 50, 75, 90, 95, and 99%ile.
 *   `<enumeration/>`: Calculates the proportions of all values individually. The
     proportions indicate the relative frequency of each bucket and are
-    calculated independently for each metric over each aggregation. The
-    proportions will sum to 1.0 for an enumeration that emits only one result
-    per page-load if it emits anything at all. An enumeration emitted more than
-    once on a page will result in proportions that total greater than 1.0.
+    calculated independently for each metric over each aggregation. (Details
+    below.)
 
 There can also be one or more `index` tags which define additional aggregation
 keys. These are a comma-separated list of keys that is appended to the standard
@@ -83,6 +81,42 @@ Currently supported additional index fields are:
 *   `profile.country`
 *   `profile.form_factor`
 
+## Enumeration Proportions
+
+Porportions are calculated against the number of "page loads" (meaning per
+"source" which is usually but not always the same as a browser page load) that
+emitted one or more values for the enumeration.  The proportions will sum to 1.0
+for an enumeration that emits only one result per page-load if it emits anything
+at all. An enumeration emitted more than once per source will result in
+proportions that total greater than 1.0 but are still relative to the total
+number of loads.
+
+For example, `Security.SiteEngagement` emits one value (either 4 or 2) per source:
+
+*   https://www.google.com/ : 4
+*   https://www.facebook.com/ : 2
+*   https://www.wikipedia.com/ : 4
+
+A proportion calculated over all sources would sum to 1.0:
+
+*   2 (0.3333)
+*   4 (0.6667)
+
+In contrast, `Blink.UseCounter.Feature` emits multiple values per source:
+
+*   https://www.google.com/ : 1, 2, 4, 6
+*   https://www.facebook.com/ : 2, 4, 5
+*   https://www.wikipedia.com/ : 1, 2, 4
+
+A proportion calculated over all sources would be:
+
+*   1 (0.6667)
+*   2 (1.0000)
+*   3 (absent)
+*   4 (1.0000)
+*   5 (0.3333)
+*   6 (0.3333)
+
 ## Get UkmRecorder instance
 
 In order to record UKM events, your code needs a UkmRecorder object, defined by [//services/metrics/public/cpp/ukm_recorder.h](https://cs.chromium.org/chromium/src/services/metrics/public/cpp/ukm_recorder.h)