Update the documentation for patterned histograms

R=mpearson@chromium.org

Bug: none
Change-Id: Ia3500bd41e7cdbb52097340100a5fba28cf2ad3a
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2415270
Commit-Queue: Ilya Sherman <isherman@chromium.org>
Reviewed-by: Mark Pearson <mpearson@chromium.org>
Reviewed-by: Weilun Shi <sweilun@chromium.org>
Auto-Submit: Ilya Sherman <isherman@chromium.org>
Cr-Commit-Position: refs/heads/master@{#813966}

tools/metrics/histograms/README.md

@@ -535,8 +535,10 @@ Do not delete histograms from histograms.xml. Instead, mark unused
 histograms as obsolete and annotate them with the date or milestone in
 the `<obsolete>` tag entry.
 
-If the histogram used [histogram suffixes](#Histogram-Suffixes), mark
-the suffix entry for the histogram as obsolete as well.
+If deprecating only some variants of a
+[patterned histogram](#Patterned-Histograms), mark each deprecated `<variant>`
+as obsolete as well. Similarly, if the histogram used histogram suffixes, mark
+the suffix entry for the histogram as obsolete.
 
 If the histogram is being replaced by a new version:
 
@@ -563,34 +565,88 @@ histogram at some point that did so even if it isn't active now.
 been recorded to. For example, it's fine to correct a typo where the histogram
 name in the metadata does not match the name in the Chromium source code.
 
-### Pattern histogram
+### Patterned Histograms
 
 It is sometimes useful to record several closely related metrics, which measure
-the same type of data, with some minor variations. It is often useful to use one
-or more <variants> elements to save on redundant verbosity in
-[histograms.xml](./histograms.xml). You can put the placeholder string in
-anywhere of the histogram name. Each placeholder string should associate with
-a single token based on the token's key. Each token can specify the `variants`
-attribute to associate with an out-of-line `<variants>` or declare a list of
-`<variant>`s as its children. These <variant>s will then replace the
-corresponding placeholder string in the histogram name to create a family of
-histograms.
-
-You can't declare ownership of `<variants>` but can declare ownership of
-`<variant>`. If there's no owner specified, the generated histograms will
-inherit owners from the parents.
+the same type of data, with some minor variations. You can declare the metadata
+for these concisely using patterned histograms. For example:
+
+```xml
+<histogram name="Pokemon.{Character}.EfficacyAgainst{OpponentType}" ...>
+  <owner>individual@chromium.org</owner>
+  <owner>team@chromium.org</owner>
+  <summary>
+    The efficacy multiplier for {Character} against an opponent of
+    {OpponentType} type.
+  </summary>
+  <token key="Character">
+    <variant name="Bulbasaur"/>
+    <variant name="Charizard"/>
+    <variant name="Mewtwo"/>
+  </token>
+  <token key="OpponentType">
+    <variant name="Dragon" summary="dragon"/>
+    <variant name="Flying" summary="flappity-flap"/>
+    <variant name="Psychic" summary="psychic"/>
+    <variant name="Water" summary="water"/>
+  </token>
+</histogram>
+```
+
+This example defines metadata for 12 (= 3 x 4) concrete histograms, such as
+
+```xml
+<histogram name="Pokemon.Charizard.EfficacyAgainstWater" ...>
+  <owner>individual@chromium.org</owner>
+  <owner>team@chromium.org</owner>
+  <summary>
+    The efficacy multiplier for Charizard against an opponent of water type.
+  </summary>
+</histogram>
+```
+
+Note that each token `<variant>` defines what text should be substituted for it,
+both in the histogram name and in the summary text. As shorthand, a `<variant>`
+that omits the `summary` attribute will substitute the value of the `name`
+attribute in the histogram's `<summary>` text as well.
+
+*** promo
+Tip: You can declare an optional token by listing an empty name: `<variant
+name="" summary="aggregated across all breakdowns"/>`. This can be useful when
+recording a "parent" histogram that aggregates across a set of breakdowns.
+***
+
+You can use the `<variants>` tag to define a set of `<variant>`s out-of-line.
+This is useful for token substitutions that are shared among multiple families
+of histograms. See
+[histograms.xml](https://source.chromium.org/search?q=file:histograms.xml%20%3Cvariants)
+for examples.
+
+By default, a `<variant>` will inherit the owners declared for the patterned
+histogram. Each variant can optionally override the inherited list with custom
+owners:
+```xml
+<variant name="SubteamBreakdown" ...>
+  <owner>subteam-lead@chromium.org</owner>
+  <owner>subteam@chromium.org</owner>
+</variant>
+```
 
 As [with histogram entries](#Cleaning-Up-Histogram-Entries), never delete
-variants. If the variant expansion is no longer used, mark it as
-obsolete.
+variants. If the variant expansion is no longer used, mark it as `<obsolete>`.
 
-If you feel unclear about which histograms will be generated from the pattern
-histogram. Consider using the `print_histogram_names.py --diff` tool to
-enumerate all the histogram names that are generated by a particular CL. e.g.
-(from the repo root):
+*** promo
+Tip: You can run `print_histogram_names.py --diff` to enumerate all the
+histogram names that are generated by a particular CL. For example, this can be
+run (from the repo root) as:
 ```
 ./tools/metrics/histograms/print_histogram_names.py --diff origin/master
 ```
+***
+
+For documentation about the `<histogram_suffixes>` syntax, which is deprecated,
+see
+https://chromium.googlesource.com/chromium/src/+/refs/tags/87.0.4270.1/tools/metrics/histograms/one-pager.md#histogram-suffixes-deprecated-in-favor-of-pattern-histograms
 
 ## When To Use Sparse Histograms