Closed Bug 1329099 Opened 3 years ago Closed 3 years ago
Document CSS Use Counters mechanism
59 bytes, text/x-review-board-request
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?
@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?
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+
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 firstname.lastname@example.org: https://hg.mozilla.org/integration/autoland/rev/d6bbe9f96def Document CSS Use Counters mechanism. r=froydnj,gfritzsche
You need to log in before you can comment on or make changes to this bug.