Conform labeled boolean metric reference page to new format

docs/user/_includes/labels-parameter.md

@@ -0,0 +1,26 @@
+#### `labels`
+
+Labeled metrics may have an optional `labels` parameter, containing a list of known labels.
+The labels in this list must match the following requirements:
+
+* Conform to the [label formatting regular expression](index.md#label-format).
+
+* Each label must have a maximum of 60 bytes, when encoded as UTF-8.
+
+* This list itself is limited to 100 labels.
+
+{{#include ../../shared/blockquote-warning.html}}
+
+##### Important
+
+> If the labels are specified in the `metrics.yaml`, using any label not listed in that file
+> will be replaced with the special value `__other__`.
+>
+> If the labels are **not** specified in the `metrics.yaml`, only 16 different dynamic labels
+> may be used, after which the special value `__other__` will be used.
+
+Removing or changing labels, including their order in the registry file, is permitted. Avoid reusing labels
+that were removed in the past. It is best practice to add documentation about removed labels to the
+description field so that analysts will know of their existence and meaning in historical data.
+Special care must be taken when changing GeckoView metrics sent through the Glean SDK, as the
+index of the labels is used to report Gecko data through the Glean SDK.

docs/user/reference/metrics/labeled_booleans.md

@@ -2,27 +2,11 @@
 
 Labeled booleans are used to record different related boolean flags.
 
-## Configuration
+## Recording API
 
-For example, you may want to record a set of flags related to accessibility (a11y).
+### `set`
 
-```YAML
+Sets one of the labels in a labeled boolean metric to a specific value.
-accessibility:
-  features:
-    type: labeled_boolean
-    description: >
-      a11y features enabled on the device. ...
-    labels:
-      - screen_reader
-      - high_contrast
-    ...
-```
-
-> **Note:** removing or changing labels, including their order in the registry file, is permitted. Avoid reusing labels that were removed in the past. It is best practice to add documentation about removed labels to the description field so that analysts will know of their existence and meaning in historical data. Special care must be taken when changing GeckoView metrics sent through the Glean SDK, as the index of the labels is used to report Gecko data through the Glean SDK.
-
-## API
-
-Now you can use the labeled boolean from the application's code:
 
 {{#include ../../../shared/tab_header.md}}
 
@@ -30,24 +14,20 @@ Now you can use the labeled boolean from the application's code:
 
 ```Kotlin
 import org.mozilla.yourApplication.GleanMetrics.Accessibility
+
 Accessibility.features["screen_reader"].set(isScreenReaderEnabled())
 Accessibility.features["high_contrast"].set(isHighContrastEnabled())
 ```
+</div>
 
-There are test APIs available too:
+<div data-lang="Java" class="tab">
 
-```Kotlin
+```Java
-import org.mozilla.yourApplication.GleanMetrics.Accessibility
+import org.mozilla.yourApplication.GleanMetrics.Accessibility;
-// Was anything recorded?
+
-assertTrue(Accessibility.features["screen_reader"].testHasValue())
+Acessibility.INSTANCE.features["screen_reader"].set(isScreenReaderEnabled());
-assertTrue(Accessibility.features["high_contrast"].testHasValue())
+Acessibility.INSTANCE.features["high_contrast"].set(isHighContrastEnabled());
-// Do the booleans have the expected values?
-assertEquals(True, Accessibility.features["screen_reader"].testGetValue())
-assertEquals(False, Accessibility.features["high_contrast"].testGetValue())
-// Did we record any invalid labels?
-assertEquals(0, Accessibility.features.testGetNumRecordedErrors(ErrorType.InvalidLabel))
 ```
-
 </div>
 
 <div data-lang="Swift" class="tab">
@@ -56,22 +36,6 @@ assertEquals(0, Accessibility.features.testGetNumRecordedErrors(ErrorType.Invali
 Accessibility.features["screen_reader"].set(isScreenReaderEnabled())
 Accessibility.features["high_contrast"].set(isHighContrastEnabled())
 ```
-
-There are test APIs available too:
-
-```Swift
-@testable import Glean
-
-// Was anything recorded?
-XCTAssert(Accessibility.features["screen_reader"].testHasValue())
-XCTAssert(Accessibility.features["high_contrast"].testHasValue())
-// Do the booleans have the expected values?
-XCTAssertEqual(true, try Accessibility.features["screen_reader"].testGetValue())
-XCTAssertEqual(false, try Accessibility.features["high_contrast"].testGetValue())
-// Were there any invalid labels?
-XCTAssertEqual(0, Accessibility.features.testGetNumRecordedErrors(.invalidLabel))
-```
-
 </div>
 
 <div data-lang="Python" class="tab">
@@ -80,54 +44,9 @@ XCTAssertEqual(0, Accessibility.features.testGetNumRecordedErrors(.invalidLabel)
 from glean import load_metrics
 metrics = load_metrics("metrics.yaml")
 
-metrics.accessibility.features["screen_reader"].set(
+metrics.accessibility.features["screen_reader"].set(is_screen_reader_enabled())
-    is_screen_reader_enabled()
+metrics.accessibility.features["high_contrast"].set(is_high_contrast_enabled())
-)
-metrics.accessibility.features["high_contrast"].set(
-    is_high_contrast_enabled()
-)
 ```
-
-There are test APIs available too:
-
-```Python
-# Was anything recorded?
-assert metrics.accessibility.features["screen_reader"].test_has_value()
-assert metrics.accessibility.features["high_contrast"].test_has_value()
-# Do the booleans have the expected values?
-assert metrics.accessibility.features["screen_reader"].test_get_value()
-assert not metrics.accessibility.features["high_contrast"].test_get_value()
-# Did we record any invalid labels?
-assert 0 == metrics.accessibility.features.test_get_num_recorded_errors(
-    ErrorType.INVALID_LABEL
-)
-```
-
-</div>
-
-<div data-lang="C#" class="tab">
-
-```C#
-using static Mozilla.YourApplication.GleanMetrics.Accessibility;
-
-Accessibility.features["screen_reader"].Set(isScreenReaderEnabled());
-Accessibility.features["high_contrast"].Set(isHighContrastEnabled());
-```
-
-There are test APIs available too:
-
-```C#
-using static Mozilla.YourApplication.GleanMetrics.Accessibility;
-// Was anything recorded?
-Assert.True(Accessibility.features["screen_reader"].TestHasValue());
-Assert.True(Accessibility.features["high_contrast"].TestHasValue());
-// Do the booleans have the expected values?
-Assert.Equal(true, Accessibility.features["screen_reader"].TestGetValue());
-Assert.Equal(false, Accessibility.features["high_contrast"].TestGetValue());
-// Did we record any invalid labels?
-Assert.Equal(0, Accessibility.features.TestGetNumRecordedErrors(ErrorType.InvalidLabel));
-```
-
 </div>
 
 <div data-lang="Rust" class="tab">
@@ -138,20 +57,222 @@ use glean_metrics;
 accessibility::features.get("screen_reader").set(is_screen_reader_enabled());
 accessibility::features.get("high_contrast").set(is_high_contrast_enabled());
 ```
+</div>
 
-There are test APIs available too:
+<div data-lang="Javascript" class="tab">
+
+```js
+import * as acessibility from "./path/to/generated/files/acessibility.js";
+
+acessibility.features["screen_reader"].set(this.isScreenReaderEnabled());
+acessibility.features["high_contrast"].set(this.isHighContrastEnabled());
+```
+</div>
+
+<div data-lang="Firefox Desktop" class="tab"></div>
+
+{{#include ../../../shared/tab_footer.md}}
+
+#### Recorded Errors
+
+* [`invalid_label`](../../user/metrics/error-reporting.md):
+  * If the label contains invalid characters. Data is still recorded to the special label `__other__`.
+  * If the label exceeds the maximum number of allowed characters. Data is still recorded to the special label `__other__`.
+
+## Testing API
+
+### `testGetValue`
+
+Gets the recorded value for a given label in a labeled boolean metric.
+
+{{#include ../../../shared/tab_header.md}}
+
+<div data-lang="Kotlin" class="tab">
+
+```Kotlin
+import org.mozilla.yourApplication.GleanMetrics.Accessibility
+
+// Do the booleans have the expected values?
+assertEquals(True, Accessibility.features["screen_reader"].testGetValue())
+assertEquals(False, Accessibility.features["high_contrast"].testGetValue())
+```
+</div>
+
+<div data-lang="Java" class="tab">
+
+```Java
+import org.mozilla.yourApplication.GleanMetrics.Accessibility;
+
+// Do the booleans have the expected values?
+assertEquals(True, Acessibility.INSTANCE.features["screen_reader"].testGetValue());
+assertEquals(False, Acessibility.INSTANCE.features["high_contrast"].testGetValue());
+```
+</div>
+
+<div data-lang="Swift" class="tab">
+
+```Swift
+@testable import Glean
+
+// Do the booleans have the expected values?
+XCTAssertEqual(true, try Accessibility.features["screen_reader"].testGetValue())
+XCTAssertEqual(false, try Accessibility.features["high_contrast"].testGetValue())
+```
+</div>
+
+<div data-lang="Python" class="tab">
+
+```Python
+from glean import load_metrics
+metrics = load_metrics("metrics.yaml")
+
+# Do the booleans have the expected values?
+assert metrics.accessibility.features["screen_reader"].test_get_value()
+assert not metrics.accessibility.features["high_contrast"].test_get_value()
+```
+</div>
+
+<div data-lang="Rust" class="tab">
+
+```rust
+use glean_metrics;
+
+// Do the booleans have the expected values?
+assert!(accessibility::features.get("screen_reader").test_get_value(None).unwrap());
+assert!(!accessibility::features.get("high_contrast").test_get_value(None).unwrap());
+```
+</div>
+
+<div data-lang="Javascript" class="tab">
+
+```js
+import * as accessibility from "./path/to/generated/files/acessibility.js";
+
+assert(await accessibility.features["screen_reader"].testGetValue());
+assert(!(await accessibility.features["high_contrast"].testGetValue()));
+```
+</div>
+
+<div data-lang="Firefox Desktop" class="tab"></div>
+
+{{#include ../../../shared/tab_footer.md}}
+
+### `testHasValue`
+
+Whether or not **any** value was recorded for a given label in a labeled boolean metric.
+
+{{#include ../../../shared/tab_header.md}}
+
+<div data-lang="Kotlin" class="tab">
+
+```Kotlin
+import org.mozilla.yourApplication.GleanMetrics.Accessibility
+
+// Was anything recorded?
+assertTrue(Accessibility.features["screen_reader"].testHasValue())
+assertTrue(Accessibility.features["high_contrast"].testHasValue())
+```
+</div>
+
+<div data-lang="Java" class="tab">
+
+```Java
+import org.mozilla.yourApplication.GleanMetrics.Accessibility;
+
+// Was anything recorded?
+assertEquals(True, Acessibility.INSTANCE.features["screen_reader"].testHasValue());
+assertEquals(True, Acessibility.INSTANCE.features["high_contrast"].testHasValue());
+```
+</div>
+
+
+<div data-lang="Swift" class="tab">
+
+```Swift
+@testable import Glean
+
+// Was anything recorded?
+XCTAssert(Accessibility.features["screen_reader"].testHasValue())
+XCTAssert(Accessibility.features["high_contrast"].testHasValue())
+```
+</div>
+
+<div data-lang="Python" class="tab">
+
+```Python
+from glean import load_metrics
+metrics = load_metrics("metrics.yaml")
+
+# Was anything recorded?
+assert metrics.accessibility.features["screen_reader"].test_has_value()
+assert metrics.accessibility.features["high_contrast"].test_has_value()
+```
+</div>
+
+<div data-lang="Rust" class="tab"></div>
+
+<div data-lang="Javascript" class="tab"></div>
+
+<div data-lang="Firefox Desktop" class="tab"></div>
+
+{{#include ../../../shared/tab_footer.md}}
+
+### `testGetNumRecordedErrors`
+
+Gets the number of errors recorded for a given labeled boolean metric in total.
+
+{{#include ../../../shared/tab_header.md}}
+
+<div data-lang="Kotlin" class="tab">
+
+```Kotlin
+import org.mozilla.yourApplication.GleanMetrics.Accessibility
+
+// Did we record any invalid labels?
+assertEquals(0, Accessibility.features.testGetNumRecordedErrors(ErrorType.InvalidLabel))
+```
+</div>
+
+<div data-lang="Java" class="tab">
+
+```Java
+import org.mozilla.yourApplication.GleanMetrics.Accessibility;
+
+// Did we record any invalid labels?
+assertEquals(0, Acessibility.INSTANCE.features.testGetNumRecordedErrors());
+```
+</div>
+
+<div data-lang="Swift" class="tab">
+
+```Swift
+@testable import Glean
+
+// Were there any invalid labels?
+XCTAssertEqual(0, Accessibility.features.testGetNumRecordedErrors(.invalidLabel))
+```
+</div>
+
+<div data-lang="Python" class="tab">
+
+```Python
+from glean import load_metrics
+metrics = load_metrics("metrics.yaml")
+
+# Did we record any invalid labels?
+assert 0 == metrics.accessibility.features.test_get_num_recorded_errors(
+    ErrorType.INVALID_LABEL
+)
+```
+</div>
+
+<div data-lang="Rust" class="tab">
 
 ```rust
 use glean::ErrorType;
 
 use glean_metrics;
 
-// Was anything recorded?
-assert!(accessibility::features.get("screen_reader").test_get_value(None).is_some());
-assert!(accessibility::features.get("high_contrast").test_get_value(None).is_some());
-// Do the booleans have the expected values?
-assert!(accessibility::features.get("screen_reader").test_get_value(None).unwrap());
-assert!(!accessibility::features.get("high_contrast").test_get_value(None).unwrap());
 // Did we record any invalid labels?
 assert_eq!(
   1,
@@ -160,37 +281,56 @@ assert_eq!(
   )
 );
 ```
-
 </div>
 
+<div data-lang="Javascript" class="tab">
+
+```js
+import * as accessibility from "./path/to/generated/files/acessibility.js";
+
+assert(await accessibility.features.testGetNumRecordedErrors("invalid_label"));
+```
+</div>
+
+<div data-lang="Firefox Desktop" class="tab"></div>
+
 {{#include ../../../shared/tab_footer.md}}
 
-## Limits
+## Metric parameters
 
-* Labels must conform to the [label formatting regular expression](index.md#label-format).
+Example labeled boolean metric definition:
 
-* Labels support lowercase alphanumeric characters; they additionally allow for dots (`.`), underscores (`_`) and/or hyphens (`-`).
+```YAML
+accessibility:
+  features:
+    type: labeled_boolean
+    description: >
+      a11y features enabled on the device.
+    bugs:
+      - https://bugzilla.mozilla.org/000000
+    data_reviews:
+      - https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
+    notification_emails:
+      - me@mozilla.com
+    expires: 2020-10-01
+    labels:
+      - screen_reader
+      - high_contrast
+      ...
+```
 
-* Each label must have a maximum of 60 bytes, when encoded as UTF-8.
+### Extra metric parameters
 
-* If the labels are specified in the `metrics.yaml`, using any label not listed in that file will be replaced with the special value `__other__`.
+{{#include ../../_includes/labels-parameter.md}}
 
-* The number of labels specified in the `metrics.yaml` is limited to 100.
+## Data questions
 
-* If the labels aren't specified in the `metrics.yaml`, only 16 different dynamic labels may be used, after which the special value `__other__` will be used.
+* Which accessibility features are enabled?
-
-## Examples
-
-* Record a related set of boolean flags.
-
-## Recorded Errors
-
-* `invalid_label`: If the label contains invalid characters. Data is still recorded to the special label `__other__`.
-
-* `invalid_label`: If the label exceeds the maximum number of allowed characters. Data is still recorded to the special label `__other__`.
 
 ## Reference
 
 * Kotlin API docs [`LabeledMetricType`](../../../javadoc/glean/mozilla.telemetry.glean.private/-labeled-metric-type/index.html), [`BooleanMetricType`](../../../javadoc/glean/mozilla.telemetry.glean.private/-boolean-metric-type/index.html)
 * Swift API docs: [`LabeledMetricType`](../../../swift/Classes/LabeledMetricType.html), [`BooleanMetricType`](../../../swift/Classes/BooleanMetricType.html)
 * Python API docs: [`LabeledMetricBase`](../../../python/glean/metrics/labeled.html), [`BooleanMetricType`](../../../python/glean/metrics/boolean.html)
+* Rust API docs: [`LabeledMetric`](../../../docs/glean/private/struct.LabeledMetric.html), [`BooleanMetricType`](../../../docs/glean/private/struct.BooleanMetric.html)
+* Javascript API docs: [`LabeledMetricType`](https://mozilla.github.io/glean.js/classes/core_metrics_types_labeled.default.html), [`BooleanMetricType`](https://mozilla.github.io/glean.js/classes/core_metrics_types_boolean.default.html)