Closed Bug 1329099 Opened 3 years ago Closed 3 years ago

Document CSS Use Counters mechanism

Categories

(Toolkit :: Telemetry, defect, P1)

defect
Points:
2

Tracking

()

RESOLVED FIXED
mozilla54
Tracking Status
firefox53 --- affected
firefox54 --- fixed

People

(Reporter: gfritzsche, Assigned: Dexter)

References

(Blocks 1 open bug)

Details

(Whiteboard: [measurement:client])

Attachments

(1 file)

Our CSS Use Counters mechanism is currently still undocumented.
We should have this documented in the in-tree docs.
This can probably live in toolkit/components/telemetry/docs/collection.
Nathan, could you do a write-up of the mechanism?
Either a patch for the docs or just a plain rough summary here that we integrate into the docs?
Flags: needinfo?(nfroyd)
Priority: P3 → P2
Priority: P2 → P1
Blocks: 1292530
Points: --- → 2
Assignee: nobody → alessio.placitelli
@Nathan, are the contents of the document complete? Did I miss or misunderstood anything?
@Georg, is the structure reasonable? Are you aware of anything that's missing from the doc?
Status: NEW → ASSIGNED
Comment on attachment 8837699 [details]
Bug 1329099 - Document CSS Use Counters mechanism.

https://reviewboard.mozilla.org/r/112748/#review115600
Attachment #8837699 - Flags: review?(nfroyd) → review+
Flags: needinfo?(nfroyd)
Comment on attachment 8837699 [details]
Bug 1329099 - Document CSS Use Counters mechanism.

https://reviewboard.mozilla.org/r/112748/#review115648

::: toolkit/components/telemetry/docs/collection/use-counters.rst:5
(Diff revision 1)
> +============
> +Use Counters
> +============
> +
> +Use counters can be used to report Telemetry statistics on whether individual documents

Nit: "are used"

::: toolkit/components/telemetry/docs/collection/use-counters.rst:6
(Diff revision 1)
> +============
> +Use Counters
> +============
> +
> +Use counters can be used to report Telemetry statistics on whether individual documents
> +use a given WebIDL method or attribute (getters and setters reported separately), CSS

"... are reported"

::: toolkit/components/telemetry/docs/collection/use-counters.rst:22
(Diff revision 1)
> +- Site *X* uses use counter *Y*.  We report "used" (true) in both the ``_DOCUMENT`` and ``_PAGE`` histograms.
> +- Site *X* does not use use counter *Y*.  We report "unused" (false) in both the ``_DOCUMENT`` and ``_PAGE`` histograms.
> +- Site *X* has an iframe for site *W*.  Site *W* uses use counter *Y*, but site *X* does not.  We report one "used" and one "unused" in the individual ``_DOCUMENT`` histogram and one "used" in the top-level ``_PAGE`` histogram.

"uses use", "use use", etc. could be reworded:
- "triggers use counter"
- "does not trigger use counter"
- etc.

::: toolkit/components/telemetry/docs/collection/use-counters.rst:39
(Diff revision 1)
> +1. a blank line;
> +2. a comment, which is a line that begins with ``//``;

Nit: I think we don't need semicolons for lists?

::: toolkit/components/telemetry/docs/collection/use-counters.rst:41
(Diff revision 1)
> +------------------------
> +Use counters for WebIDL methods/attributes and CSS properties are registered in the `UseCounters.conf <https://dxr.mozilla.org/mozilla-central/source/dom/base/UseCounters.conf>`_ file.  The format of this file is very strict. Each line can be:
> +
> +1. a blank line;
> +2. a comment, which is a line that begins with ``//``;
> +3. one of three possible use counter declarations:

This line is rendered bold when you build it.

::: toolkit/components/telemetry/docs/collection/use-counters.rst:48
(Diff revision 1)
> +    * ``attribute <IDL interface name>.<IDL attribute name>``
> +    * ``property <CSS property method name>``
> +
> +CSS properties
> +~~~~~~~~~~~~~~
> +The CSS property method name should be identical to the |method| argument of ``CSS_PROP()`` and related macros.  The only differences are that all hyphens are removed and CamelCase naming is used.  See `nsCSSPropList.h <https://dxr.mozilla.org/mozilla-central/source/layout/style/nsCSSPropList.h>`_ for further details.

Building the docs i see:

<..>/use-counters.rst:48: ERROR: Undefined substitution referenced: "method".

Use backticks here?

::: toolkit/components/telemetry/docs/collection/use-counters.rst:60
(Diff revision 1)
> +
> +The processor script
> +====================
> +The definition files are processed twice:
> +
> +- once used to generate two C++ headers files, included by the web platform components (e.g. DOM) that own the features to be tracked;

"once to generate ..."
Attachment #8837699 - Flags: review?(gfritzsche) → review+
Pushed by alessio.placitelli@gmail.com:
https://hg.mozilla.org/integration/autoland/rev/d6bbe9f96def
Document CSS Use Counters mechanism. r=froydnj,gfritzsche
https://hg.mozilla.org/mozilla-central/rev/d6bbe9f96def
Status: ASSIGNED → RESOLVED
Closed: 3 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla54
You need to log in before you can comment on or make changes to this bug.