NO BUG - Fix reStructuredText warnings
authorGregory Szorc <gps@mozilla.com>
Sun, 01 Mar 2015 22:51:32 -0800
changeset 231294 297f6188f37ccac6401e5dea1bbe165b03fedbb0
parent 231293 3dac1282a10f39d89a7f8ff0c9cb3b52489cf934
child 231295 07bf3ce1c8897f2f7cdf0f68517397493c462dad
push id28348
push userkwierso@gmail.com
push dateMon, 02 Mar 2015 20:13:43 +0000
treeherdermozilla-central@abb7f0d180da [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
milestone39.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
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)
browser/base/content/docs/sslerrorreport/dataformat.rst
browser/base/content/docs/sslerrorreport/index.rst
browser/docs/UITelemetry.rst
build/docs/defining-binaries.rst
mobile/android/base/docs/uitelemetry.rst
services/cloudsync/docs/dataformat.rst
services/docs/metrics.rst
services/healthreport/docs/dataformat.rst
toolkit/components/crashes/docs/crash-events.rst
toolkit/modules/docs/AsyncShutdown.rst
toolkit/modules/docs/index.rst
--- a/browser/base/content/docs/sslerrorreport/dataformat.rst
+++ b/browser/base/content/docs/sslerrorreport/dataformat.rst
@@ -1,9 +1,9 @@
-.. _healthreport_dataformat:
+.. _sslerrorreport_dataformat:
 
 ==============
 Payload Format
 ==============
 
 An example report::
 
   {
--- a/browser/base/content/docs/sslerrorreport/index.rst
+++ b/browser/base/content/docs/sslerrorreport/index.rst
@@ -1,9 +1,9 @@
-.. _sslerrorreport
+.. _sslerrorreport:
 
 ===================
 SSL Error Reporting
 ===================
 
 With the introduction of HPKP, it becomes useful to be able to capture data
 on pin violations. SSL Error Reporting is an opt-in mechanism to allow users
 to send data on such violations to mozilla.
--- a/browser/docs/UITelemetry.rst
+++ b/browser/docs/UITelemetry.rst
@@ -1,17 +1,17 @@
 =======================
 UITelemetry data format
 =======================
 
 UI Telemetry sends its data as a JSON blob. This document describes the different parts
 of the JSON blob.
 
 ``toolbars``
-------------
+============
 
 This tracks the state of the user's UI customizations. It has the following properties:
 
 - ``sizemode`` - string indicating whether the window is in maximized, normal (restored) or
   fullscreen mode;
 - ``bookmarksBarEnabled`` - boolean indicating whether the bookmarks bar is visible;
 - ``menuBarEnabled`` - boolean indicating whether the menu bar is visible (always false on OS X);
 - ``titleBarEnabled`` - boolean indicating whether the (real) titlebar is visible (rather than
@@ -29,25 +29,26 @@ This tracks the state of the user's UI c
 - ``addonToolbars`` - the number of non-default toolbars that are customizable. 1 by default
   because it counts the add-on bar shim;
 - ``visibleTabs`` - array of the number of visible tabs per window;
 - ``hiddenTabs`` - array of the number of hidden tabs per window (ie tabs in panorama groups which
   are not the current group);
 - ``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
 things happen.
 
 ``countableEvents`` contains a list of buckets as its properties. A bucket represents the state the browser was in when these events occurred, such as currently running an interactive tour. There are 3 types of buckets:
 
 - ``__DEFAULT__`` - No bucket, for times when the browser is not in any special state.
@@ -61,58 +62,64 @@ Each bucket is an object with the follow
   storing a number indicating how often the respective type of click has happened.
 - ``click-menu-button`` is the same, except the item ID is always 'button'.
 - ``click-bookmarks-bar`` is the same, with the item IDs being replaced by either ``container`` for
   clicks on bookmark or livemark folders, and ``item`` for individual bookmarks.
 - ``click-menubar`` is similar, with the item IDs being replaced by one of ``menu``, ``menuitem``
   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).
     - ``selection`` searches records selections of search suggestions.  They include
       the source, the index of the selection, and the kind of selection (mouse or
       enter key).  Selection searches are also counted in their sources.
 
 
 
 ``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``.
 
 Page IDs are also used to identify buckets for :ref:`UITelemetry_countableEvents`, in the following circumstances:
 
 - The current tab is a tour page. This will be a normal bucket with the name ``UITour|<PAGEID>``, where ``<PAGEID>`` is the page's registered ID. This will result in bucket IDs such as ``bucket_UITour|australis-tour``.
 - A tour tab is open but another tab is active. This will be an expiring bucket with the name ``UITour|<PAGEID>|inactive``. This will result in bucket IDs such as ``bucket_UITour|australis-tour|inactive|1m``.
 - A tour tab has recently been open but has been closed. This will be an expiring bucket with the name ``UITour|<PAGEID>|closed``. This will result in bucket IDs such as ``bucket_UITour|australis-tour|closed|10m``.
 
 
 
 ``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:
 
 - ``selection`` if there is content on the page that's selected on which the user clicks;
 - ``link`` if the user opened the context menu for a link
 - ``image-link`` if the user opened the context menu on an image or canvas that's a link;
 - ``image`` if the user opened the context menu on an image (that isn't a link);
--- a/build/docs/defining-binaries.rst
+++ b/build/docs/defining-binaries.rst
@@ -16,16 +16,18 @@ Source files
 Source files to be used in a given directory are registered in the ``SOURCES``
 and ``UNIFIED_SOURCES`` variables. ``UNIFIED_SOURCES`` have a special behavior
 in that they are aggregated by batches of 16, requiring, for example, that there
 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',
        'ThirdSource.cpp',
    ]
 
    SOURCES += [
        'OtherSource.cpp',
@@ -36,31 +38,37 @@ for C, C++, and Objective C.
 
 
 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
 Windows.
 
 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',
    ]
 
 Note that the leaf name in those paths is the ``Library`` name, not an actual
 file name.
 
@@ -77,82 +85,94 @@ Intermediate (Static) Libraries
 ===============================
 
 In many cases in the tree, static libraries are built with the only purpose
 of being linked into another, bigger one (like libxul). Instead of adding all
 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
 in the tree.
 
 As a special rule, those intermediate libraries don't need a ``Library`` name
 for themselves.
 
 
 Shared Libraries
 ================
 
 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
 build both types of libraries.
 
 With a ``SharedLibrary`` name of ``foo``, the library file name will be
 ``libfoo.dylib`` on OSX, ``libfoo.so`` on ELF systems (Linux, etc.), and
 ``foo.dll`` on Windows. On Windows, there is also an import library named
 ``foo.lib``, used on the linker command line. ``libfoo.dylib`` and
 ``libfoo.so`` are considered the import library name for, resp. OSX and ELF
 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``.
 This template however affects the behavior on all platforms, so it needs to
 be set only on OSX.
 
 
 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,
 it will be ``foobar.exe``.
 
 Like static and shared libraries, the build system can be instructed to link
 libraries to the executable with ``USE_LIBS``, listing various ``Library``
 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',
    ])
 
 Contrary to ``Program``, which requires corresponding ``SOURCES``, when using
 ``SimplePrograms``, the corresponding ``SOURCES`` are implied. If the
 corresponding ``sources`` have an extension different from ``.cpp``, it is
 possible to specify the proper extension:
 
+.. code-block:: python
+
    SimplePrograms([
        'ThirdProgram',
        'FourthProgram',
    ], ext='.c')
 
 Please note this construct was added for compatibility with what already lives
 in the mozilla tree ; it is recommended not to add new simple programs with
 sources with a different extension than ``.cpp``.
@@ -165,28 +185,32 @@ if it's different from ``.cpp``.
 
 Linking with system libraries
 =============================
 
 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',
    ]
 
 This expands to ``foo.lib bar.lib`` when building with MSVC, and
 ``-lfoo -lbar`` otherwise.
 
 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)
 
 Like ``USE_LIBS``, this variable applies to static and shared libraries, as
 well as programs.
 
 
@@ -196,63 +220,73 @@ Libraries from third party build system
 Some libraries in the tree are not built by the moz.build-governed build
 system, and there is no ``Library`` corresponding to them.
 
 However, ``USE_LIBS`` allows to reference such libraries by giving a full
 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',
    ]
 
 Note that ``/path/from/topsrcdir/to/third-party`` and
 ``../relative/third-party/baz`` must lead under a subconfigured directory (a
 directory with an AC_OUTPUT_SUBDIRS in configure.in), or ``security/nss``.
 
 
 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
 
 But because static libraries and Windows import libraries have the same file
 names, either the static or the shared library name needs to be different
 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'
 
 With the above, on Windows, ``foo_s.lib`` will be the static library,
 ``foo.dll`` the shared library, and ``foo.lib`` the import 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']
 
 This allows to use ``mylib`` in the ``USE_LIBS`` of another library or
 executable.
 
 When refering to a ``Library`` name building both types of libraries in
 ``USE_LIBS``, the shared library is chosen to be linked. But sometimes,
 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
       FORCE_STATIC_LIB = True
       STATIC_LIBRARY_NAME = 'mylib_s'
    b/moz.build:
       Program('myprog')
       USE_LIBS += [
@@ -267,16 +301,18 @@ The ``SDK_LIBRARY`` boolean variable def
 directory is going to be installed in the SDK.
 
 The ``SONAME`` variable declares a "shared object name" for the library. It
 defaults to the ``Library`` name or the ``SHARED_LIBRARY_NAME`` if set. When
 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:
       Library('otherlib')
       SONAME = 'foo'
    c/moz.build:
       Program('myprog')
       USE_LIBS += [
--- a/mobile/android/base/docs/uitelemetry.rst
+++ b/mobile/android/base/docs/uitelemetry.rst
@@ -67,17 +67,17 @@ Events capture key occurrences. They sho
 
 ``extras`` (Optional)
   For extra information that may be useful in understanding the event. Make an effort to keep this brief.
 
 ``timestamp`` (Optional)
   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``.
 
 
 Clock
 =====
 
 Times are relative to either elapsed realtime (an arbitrary monotonically increasing clock that continues to tick when the device is asleep), or elapsed uptime (which doesn't tick when the device is in deep sleep). We default to elapsed realtime.
--- a/services/cloudsync/docs/dataformat.rst
+++ b/services/cloudsync/docs/dataformat.rst
@@ -1,13 +1,13 @@
 .. _cloudsync_dataformat:
 
-=========
+===========
 Data Format
-=========
+===========
 
 All fields are required unless noted otherwise.
 
 Bookmarks
 =========
 
 Record
 ------
--- a/services/docs/metrics.rst
+++ b/services/docs/metrics.rst
@@ -8,17 +8,17 @@ The ``services/metrics`` directory conta
 collecting and persisting framework for Gecko applications.
 
 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
 -------------------------
 
 Telemetry provides similar features to code in this directory. The two
 may be unified in the future.
 
 Usage
--- a/services/healthreport/docs/dataformat.rst
+++ b/services/healthreport/docs/dataformat.rst
@@ -663,17 +663,17 @@ Example
         "foreignInstall": false,
         "hasBinaryComponents": false,
         "installDay": 16093,
         "updateDay": 16093
       }
     }
 
 org.mozilla.addons.plugins
--------------------------
+--------------------------
 
 This measurement contains information about the currently-installed plugins.
 
 Version 1
 ^^^^^^^^^
 
 The measurement object is a mapping of plugin IDs to objects containing
 plugin metadata.
@@ -692,17 +692,17 @@ Each plugin contains the following prope
 * mimeTypes
 * updateDay
 
 With the exception of *updateDay* and *mimeTypes*, all these properties come
 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
 ^^^^^^^
 
 ::
 
     "org.mozilla.addons.plugins": {
       "_v": 1,
--- a/toolkit/components/crashes/docs/crash-events.rst
+++ b/toolkit/components/crashes/docs/crash-events.rst
@@ -70,17 +70,17 @@ crash.main.1
 
 This event is produced when the main process crashes.
 
 The payload of this event is the string crash ID, very likely a UUID.
 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.
 
 The payload of this event is delimited by UNIX newlines (*\n*) and contains the
 following fields:
 
 * The crash ID string
 * "true" if the submission succeeded or "false" otherwise
--- a/toolkit/modules/docs/AsyncShutdown.rst
+++ b/toolkit/modules/docs/AsyncShutdown.rst
@@ -3,47 +3,49 @@
 ==============
 AsyncShutdown
 ==============
 
 During shutdown of the process, subsystems are closed one after another. ``AsyncShutdown`` is a module dedicated to express shutdown-time dependencies between:
 - 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;
 - wait until the clients have completed their final operations based on FooService (often asynchronously);
 - only then shut itself down.
 
 This may be expressed as an instance of ``AsyncShutdown.Barrier``. An instance of ``AsyncShutdown.Barrier`` provides:
 - a capability ``client`` that may be published to clients, to let them register or unregister blockers;
 - 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
 remove their blockers (`awake` meaning that seconds during which the
 computer is asleep or too busy to do anything are not counted). This
 mechanism helps ensure that we do not leave the process in a state in
 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.
 
 .. code-block:: javascript
 
     // Some client of FooService called FooClient
 
     Components.utils.import("resource://gre/modules/FooService.jsm", this);
@@ -53,17 +55,17 @@ The following snippet presents an exampl
     FooService.shutdown.addBlocker(
       "FooClient: Need to make sure that we have reached some state",
       () => promiseReachedSomeState
     );
     // promiseReachedSomeState should be an instance of Promise resolved once
     // 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
 outstanding operations before FooService shuts down.
 
 .. code-block:: javascript
 
     // Module FooService
@@ -86,20 +88,20 @@ outstanding operations before FooService
       yield shutdown.wait();
 
       // Now deactivate FooService itself.
       // ...
     });
 
 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.
 
 .. code-block:: javascript
 
     // Some client of FooService called FooClient2
 
     Components.utils.import("resource://gre/modules/FooService.jsm", this);
@@ -136,17 +138,17 @@ The following snippet presents FooClient
 
         yield FooService.oneLastCall();
         this.state = "Ready";
       }.bind(this)
     };
 
 
 Example 4: A service with both internal and external dependencies
--------------------------------------------------------
+-----------------------------------------------------------------
 
  .. code-block:: javascript
 
     // Module FooService2
 
     Components.utils.import("resource://gre/modules/AsyncShutdown.jsm", this);
     Components.utils.import("resource://gre/modules/Task.jsm", this);
     Components.utils.import("resource://gre/modules/Promise.jsm", this);
@@ -206,20 +208,20 @@ Example 4: A service with both internal 
 
       // Wait for all instances of FooConnection to be closed.
       yield connections.wait();
 
       // Now finish shutting down FooService2
       // ...
     });
 
+.. _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);
 - ``webWorkersShutdown`` (once this phase is complete, JavaScript does not have access to workers anymore);
 - ...
 
 Much as services, phases have clients. For instance, all users of web workers MUST have finished using their web workers before the end of phase ``webWorkersShutdown``.
 
@@ -250,10 +252,8 @@ List of phases
   during observer notification "profile-before-change2". Once the
   barrier is resolved, Telemetry must stop its operations.
 
 ``AsyncShutdown.webWorkersShutdown``
 
   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.
-
-
--- a/toolkit/modules/docs/index.rst
+++ b/toolkit/modules/docs/index.rst
@@ -1,10 +1,10 @@
-==============
+===============
 Toolkit modules
-==============
+===============
 
 The ``/toolkit/modules`` directory contains a number of self-contained toolkit modules considered small enough that they do not deserve individual directories.
 
 .. toctree::
   :maxdepth: 1
 
   AsyncShutdown