From 714d70c1e76d428ec12f43fe6cc713fcefbd4fa8 Mon Sep 17 00:00:00 2001 From: Gregory Szorc Date: Sun, 1 Mar 2015 22:51:32 -0800 Subject: [PATCH] NO BUG - Fix reStructuredText warnings Sphinx has been complaining about a number of reStructuredText warnings for a while. Fix all the ones in .rst files. Not asking for review because this is docs only and changing .rst files can't break anything important. DONTBUILD (NPOTB) --- .../docs/sslerrorreport/dataformat.rst | 2 +- .../content/docs/sslerrorreport/index.rst | 2 +- browser/docs/UITelemetry.rst | 39 +++++++++++-------- build/docs/defining-binaries.rst | 36 +++++++++++++++++ mobile/android/base/docs/uitelemetry.rst | 2 +- services/cloudsync/docs/dataformat.rst | 4 +- services/docs/metrics.rst | 2 +- services/healthreport/docs/dataformat.rst | 4 +- .../components/crashes/docs/crash-events.rst | 2 +- toolkit/modules/docs/AsyncShutdown.rst | 24 ++++++------ toolkit/modules/docs/index.rst | 4 +- 11 files changed, 82 insertions(+), 39 deletions(-) diff --git a/browser/base/content/docs/sslerrorreport/dataformat.rst b/browser/base/content/docs/sslerrorreport/dataformat.rst index 18292562629..b3b8513f412 100644 --- a/browser/base/content/docs/sslerrorreport/dataformat.rst +++ b/browser/base/content/docs/sslerrorreport/dataformat.rst @@ -1,4 +1,4 @@ -.. _healthreport_dataformat: +.. _sslerrorreport_dataformat: ============== Payload Format diff --git a/browser/base/content/docs/sslerrorreport/index.rst b/browser/base/content/docs/sslerrorreport/index.rst index b9db28e1891..2c421011321 100644 --- a/browser/base/content/docs/sslerrorreport/index.rst +++ b/browser/base/content/docs/sslerrorreport/index.rst @@ -1,4 +1,4 @@ -.. _sslerrorreport +.. _sslerrorreport: =================== SSL Error Reporting diff --git a/browser/docs/UITelemetry.rst b/browser/docs/UITelemetry.rst index 3103d71df00..dac1f5e53da 100644 --- a/browser/docs/UITelemetry.rst +++ b/browser/docs/UITelemetry.rst @@ -6,7 +6,7 @@ UI Telemetry sends its data as a JSON blob. This document describes the differen of the JSON blob. ``toolbars`` ------------- +============ This tracks the state of the user's UI customizations. It has the following properties: @@ -34,15 +34,16 @@ This tracks the state of the user's UI customizations. It has the following prop - ``countableEvents`` - please refer to the next section. - ``durations`` - an object mapping descriptions to duration records, which records the amount of time a user spent doing something. Currently only has one property: - - ``customization`` - how long a user spent customizing the browser. This is an array of - objects, where each object has a ``duration`` property indicating the time in milliseconds, - and a ``bucket`` property indicating a bucket in which the duration info falls. + + - ``customization`` - how long a user spent customizing the browser. This is an array of + objects, where each object has a ``duration`` property indicating the time in milliseconds, + and a ``bucket`` property indicating a bucket in which the duration info falls. .. _UITelemetry_countableEvents: ``countableEvents`` -------------------- +=================== Countable events are stored under the ``toolbars`` section. They count the number of times certain events happen. No timing or other correlating information is stored - purely the number of times @@ -66,23 +67,27 @@ Each bucket is an object with the following properties: or ``other``, depending on the kind of item clicked. Note that this is not tracked on OS X, where we can't listen for these events because of the global menubar. - ``click-bookmarks-menu-button`` is also similar, with the item IDs being replaced by: - - ``menu`` for clicks on the 'menu' part of the item; - - ``add`` for clicks that add a bookmark; - - ``edit`` for clicks that open the panel to edit an existing bookmark; - - ``in-panel`` for clicks when the button is in the menu panel, and clicking it does none of the + + - ``menu`` for clicks on the 'menu' part of the item; + - ``add`` for clicks that add a bookmark; + - ``edit`` for clicks that open the panel to edit an existing bookmark; + - ``in-panel`` for clicks when the button is in the menu panel, and clicking it does none of the above; - ``customize`` tracks different types of customization events without the ``left``, ``middle`` and ``right`` distinctions. The different events are the following, with each storing a count of the number of times they occurred: - - ``start`` counts the number of times the user starts customizing; - - ``add`` counts the number of times an item is added somewhere from the palette; - - ``move`` counts the number of times an item is moved somewhere else (but not to the palette); - - ``remove`` counts the number of times an item is removed to the palette; - - ``reset`` counts the number of times the 'restore defaults' button is used; + + - ``start`` counts the number of times the user starts customizing; + - ``add`` counts the number of times an item is added somewhere from the palette; + - ``move`` counts the number of times an item is moved somewhere else (but not to the palette); + - ``remove`` counts the number of times an item is removed to the palette; + - ``reset`` counts the number of times the 'restore defaults' button is used; - ``search`` is an object tracking searches of various types, keyed off the search location, storing a number indicating how often the respective type of search has happened. + - There are also two special keys that mean slightly different things. + - ``urlbar-keyword`` records searches that would have been an invalid-protocol error, but are now keyword searches. They are also counted in the ``urlbar`` keyword (along with all the other urlbar searches). @@ -93,7 +98,8 @@ Each bucket is an object with the following properties: ``UITour`` ----------- +========== + The UITour API provides ways for pages on trusted domains to safely interact with the browser UI and request it to perform actions such as opening menus and showing highlights over the browser chrome - for the purposes of interactive tours. We track some usage of this API via the ``UITour`` object in the UI Telemetry output. Each page is able to register itself with an identifier, a ``Page ID``. A list of Page IDs that have been seen over the last 8 weeks is available via ``seenPageIDs``. @@ -107,7 +113,8 @@ Page IDs are also used to identify buckets for :ref:`UITelemetry_countableEvents ``contextmenu`` ---------------- +=============== + We track context menu interactions to figure out which ones are most often used and/or how effective they are. In the ``contextmenu`` object, we first store things per-bucket. Next, we divide the following different context menu situations: diff --git a/build/docs/defining-binaries.rst b/build/docs/defining-binaries.rst index 9ef0d727963..97dadbbd595 100644 --- a/build/docs/defining-binaries.rst +++ b/build/docs/defining-binaries.rst @@ -21,6 +21,8 @@ are no conflicting variables in those source files. ``SOURCES`` and ``UNIFIED_SOURCES`` are lists which must be appended to, and each append requires the given list to be alphanumerically ordered. +.. code-block:: python + UNIFIED_SOURCES += [ 'FirstSource.cpp', 'SecondSource.cpp', @@ -41,6 +43,8 @@ Static Libraries To build a static library, other than defining the source files (see above), one just needs to define a library name with the ``Library`` template. +.. code-block:: python + Library('foo') The library file name will be ``libfoo.a`` on UNIX systems and ``foo.lib`` on @@ -50,12 +54,16 @@ If the static library needs to aggregate other static libraries, a list of ``Library`` names can be added to the ``USE_LIBS`` variable. Like ``SOURCES``, it requires the appended list to be alphanumerically ordered. +.. code-block:: python + USE_LIBS += ['bar', 'baz'] If there are multiple directories containing the same ``Library`` name, it is possible to disambiguate by prefixing with the path to the wanted one (relative or absolute): +.. code-block:: python + USE_LIBS += [ '/path/from/topsrcdir/to/bar', '../relative/baz', @@ -82,6 +90,8 @@ required libraries to ``USE_LIBS`` for the bigger one, it is possible to tell the build system that the library built in the current directory is meant to be linked to that bigger library, with the ``FINAL_LIBRARY`` variable. +.. code-block:: python + FINAL_LIBRARY = 'xul' The ``FINAL_LIBRARY`` value must match a unique ``Library`` name somewhere @@ -98,6 +108,8 @@ Sometimes, we want shared libraries, a.k.a. dynamic libraries. Such libraries are defined similarly to static libraries, using the ``SharedLibrary`` template instead of ``Library``. +.. code-block:: python + SharedLibrary('foo') When this template is used, no static library is built. See further below to @@ -113,6 +125,8 @@ systems. On OSX, one may want to create a special kind of dynamic library: frameworks. This is done with the ``Framework`` template. +.. code-block:: python + Framework('foo') With a ``Framework`` name of ``foo``, the framework file name will be ``foo``. @@ -126,6 +140,8 @@ Executables Executables, a.k.a. programs, are, in the simplest form, defined with the ``Program`` template. +.. code-block:: python + Program('foobar') On UNIX systems, the executable file name will be ``foobar``, while on Windows, @@ -138,6 +154,8 @@ names. In some cases, we want to create an executable per source file in the current directory, in which case we can use the ``SimplePrograms`` template +.. code-block:: python + SimplePrograms([ 'FirstProgram', 'SecondProgram', @@ -148,6 +166,8 @@ Contrary to ``Program``, which requires corresponding ``SOURCES``, when using corresponding ``sources`` have an extension different from ``.cpp``, it is possible to specify the proper extension: +.. code-block:: python + SimplePrograms([ 'ThirdProgram', 'FourthProgram', @@ -170,6 +190,8 @@ Programs and libraries usually need to link with system libraries, such as a widget toolkit, etc. Those required dependencies can be given with the ``OS_LIBS`` variable. +.. code-block:: python + OS_LIBS += [ 'foo', 'bar', @@ -182,6 +204,8 @@ For convenience with ``pkg-config``, ``OS_LIBS`` can also take linker flags such as ``-L/some/path`` and ``-llib``, such that it is possible to directly assign ``LIBS`` variables from ``CONFIG``, such as: +.. code-block:: python + OS_LIBS += CONFIG['MOZ_PANGO_LIBS'] (assuming ``CONFIG['MOZ_PANGO_LIBS']`` is a list, not a string) @@ -201,6 +225,8 @@ path (like when disambiguating identical ``Library`` names). The same naming rules apply as other uses of ``USE_LIBS``, so only the library name without prefix and suffix shall be given. +.. code-block:: python + USE_LIBS += [ '/path/from/topsrcdir/to/third-party/bar', '../relative/third-party/baz', @@ -217,6 +243,8 @@ Building both static and shared libraries When both types of libraries are required, one needs to set both ``FORCE_SHARED_LIB`` and ``FORCE_STATIC_LIB`` boolean variables. +.. code-block:: python + FORCE_SHARED_LIB = True FORCE_STATIC_LIB = True @@ -227,6 +255,8 @@ than the name given to the ``Library`` template. The ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME`` variables can be used to change either the static or the shared library name. +.. code-block:: python + Library('foo') STATIC_LIBRARY_NAME = 'foo_s' @@ -236,6 +266,8 @@ With the above, on Windows, ``foo_s.lib`` will be the static library, In some cases, for convenience, it is possible to set both ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME``. For example: +.. code-block:: python + Library('mylib') STATIC_LIBRARY_NAME = 'mylib_s' SHARED_LIBRARY_NAME = CONFIG['SHARED_NAME'] @@ -248,6 +280,8 @@ When refering to a ``Library`` name building both types of libraries in it is wanted to link the static version, in which case the ``Library`` name needs to be prefixed with ``static:`` in ``USE_LIBS`` +:: + a/moz.build: Library('mylib') FORCE_SHARED_LIB = True @@ -272,6 +306,8 @@ linking to a library with a ``SONAME``, the resulting library or program will have a dependency on the library with the name corresponding to the ``SONAME`` instead of the ``Library`` name. This only impacts ELF systems. +:: + a/moz.build: Library('mylib') b/moz.build: diff --git a/mobile/android/base/docs/uitelemetry.rst b/mobile/android/base/docs/uitelemetry.rst index 0583fb0d4f4..16374ed1992 100644 --- a/mobile/android/base/docs/uitelemetry.rst +++ b/mobile/android/base/docs/uitelemetry.rst @@ -72,7 +72,7 @@ Events capture key occurrences. They should be brief and simple, and should not The time at which the event occurred. If not specified, this field defaults to the current value of the realtime clock. Versioning -======== +========== As a we improve on our Telemetry methods, it is foreseeable that our probes will change over time. Different versions of a probe could carry different data or have different interpretations on the server-side. To make it easier for the server to handle these changes, you should add version numbers to your event and session names. An example of a versioned session is ``homepanel.1``; this is version 1 of the ``homepanel`` session. This approach should also be applied to event names, an example being: ``panel.enable.1`` and ``panel.enable.2``. diff --git a/services/cloudsync/docs/dataformat.rst b/services/cloudsync/docs/dataformat.rst index ac4341cce13..9165814598e 100644 --- a/services/cloudsync/docs/dataformat.rst +++ b/services/cloudsync/docs/dataformat.rst @@ -1,8 +1,8 @@ .. _cloudsync_dataformat: -========= +=========== Data Format -========= +=========== All fields are required unless noted otherwise. diff --git a/services/docs/metrics.rst b/services/docs/metrics.rst index 560448e18f7..41fc3ea2d46 100644 --- a/services/docs/metrics.rst +++ b/services/docs/metrics.rst @@ -13,7 +13,7 @@ Overview The Metrics framework by itself doesn't do much: it simply provides a generic mechanism for collecting and persisting data. It is up to users of this framework to drive collection and do something with the obtained -data. A consumer of this framework is :ref:`firefox_health_report`. +data. A consumer of this framework is :ref:`healthreport`. Relationship to Telemetry ------------------------- diff --git a/services/healthreport/docs/dataformat.rst b/services/healthreport/docs/dataformat.rst index 575b01ba7cd..bdf0edb0869 100644 --- a/services/healthreport/docs/dataformat.rst +++ b/services/healthreport/docs/dataformat.rst @@ -668,7 +668,7 @@ Example } org.mozilla.addons.plugins -------------------------- +-------------------------- This measurement contains information about the currently-installed plugins. @@ -697,7 +697,7 @@ directly from ``nsIPluginTag`` via ``nsIPluginHost``. *updateDay* is the number of days since UNIX epoch of the plugins last modified time. *mimeTypes* is the list of mimetypes the plugin supports, see -``nsIPluginTag.getMimeTypes()`. +``nsIPluginTag.getMimeTypes()``. Example ^^^^^^^ diff --git a/toolkit/components/crashes/docs/crash-events.rst b/toolkit/components/crashes/docs/crash-events.rst index 2550317058d..9ad33e375c0 100644 --- a/toolkit/components/crashes/docs/crash-events.rst +++ b/toolkit/components/crashes/docs/crash-events.rst @@ -75,7 +75,7 @@ There should be ``UUID.dmp`` and ``UUID.extra`` files on disk, saved by Breakpad. crash.submission.1 -^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^ This event is produced when a crash is submitted. diff --git a/toolkit/modules/docs/AsyncShutdown.rst b/toolkit/modules/docs/AsyncShutdown.rst index bfdc61cb267..0a9d68256d9 100644 --- a/toolkit/modules/docs/AsyncShutdown.rst +++ b/toolkit/modules/docs/AsyncShutdown.rst @@ -8,9 +8,10 @@ During shutdown of the process, subsystems are closed one after another. ``Async - services and their clients; - shutdown phases (e.g. profile-before-change) and their clients. -.. _AsyncShutdown Barriers: +.. _AsyncShutdown_Barriers: + Barriers: Expressing shutdown dependencies towards a service -========================================== +============================================================ Consider a service FooService. At some point during the shutdown of the process, this service needs to: - inform its clients that it is about to shut down; @@ -22,7 +23,7 @@ This may be expressed as an instance of ``AsyncShutdown.Barrier``. An instance o - methods for the owner of the barrier to let it consult the state of blockers and wait until all client-registered blockers have been resolved. Shutdown timeouts ------------------- +----------------- By design, an instance of ``AsyncShutdown.Barrier`` will cause a crash if it takes more than 60 seconds `awake` for its clients to lift or @@ -34,11 +35,12 @@ which it can neither proceed with shutdown nor be relaunched. If the CrashReporter is enabled, this crash will report: - the name of the barrier that failed; - for each blocker that has not been released yet: + - the name of the blocker; - the state of the blocker, if a state function has been provided (see :ref:`AsyncShutdown.Barrier.state`). Example 1: Simple Barrier client ----------------------------- +-------------------------------- The following snippet presents an example of a client of FooService that has a shutdown dependency upon FooService. In this case, the client wishes to ensure that FooService is not shutdown before some state has been reached. An example is clients that need write data asynchronously and need to ensure that they have fully written their state to disk before shutdown, even if due to some user manipulation shutdown takes place immediately. @@ -58,7 +60,7 @@ The following snippet presents an example of a client of FooService that has a s // we have reached the expected state Example 2: Simple Barrier owner ----------------------------- +------------------------------- The following snippet presents an example of a service FooService that wishes to ensure that all clients have had a chance to complete any @@ -91,10 +93,10 @@ outstanding operations before FooService shuts down. Frequently, a service that owns a ``AsyncShutdown.Barrier`` is itself a client of another Barrier. -.. _AsyncShutdown.Barrier.prototype.state: +.. _AsyncShutdown.Barrier.state: Example 3: More sophisticated Barrier client --------------------------------------- +-------------------------------------------- The following snippet presents FooClient2, a more sophisticated client of FooService that needs to perform a number of operations during shutdown but before the shutdown of FooService. Also, given that this client is more sophisticated, we provide a function returning the state of FooClient2 during shutdown. If for some reason FooClient2's blocker is never lifted, this state can be reported as part of a crash report. @@ -141,7 +143,7 @@ The following snippet presents FooClient2, a more sophisticated client of FooSer Example 4: A service with both internal and external dependencies -------------------------------------------------------- +----------------------------------------------------------------- .. code-block:: javascript @@ -211,10 +213,10 @@ Example 4: A service with both internal and external dependencies // ... }); +.. _AsyncShutdown_phases: -.. _AsyncShutdown phases: Phases: Expressing dependencies towards phases of shutdown -=========================================== +========================================================== The shutdown of a process takes place by phase, such as: - ``profileBeforeChange`` (once this phase is complete, there is no guarantee that the process has access to a profile directory); @@ -255,5 +257,3 @@ List of phases The client capability for clients wishing to block asynchronously during observer notification "web-workers-shutdown". Once the phase is complete, clients MUST NOT use web workers. - - diff --git a/toolkit/modules/docs/index.rst b/toolkit/modules/docs/index.rst index cdd466e66e3..8e476c86a99 100644 --- a/toolkit/modules/docs/index.rst +++ b/toolkit/modules/docs/index.rst @@ -1,6 +1,6 @@ -============== +=============== Toolkit modules -============== +=============== The ``/toolkit/modules`` directory contains a number of self-contained toolkit modules considered small enough that they do not deserve individual directories.