Bug 1747815 - [devtools] Document sources and source-actors reducers. r=bomsy FIREFOX_BETA_97_BASE
authorAlexandre Poirot <poirot.alex@gmail.com>
Sun, 09 Jan 2022 22:16:50 +0000
changeset 604035 b81970e39db444fa9a70eaf2e656f3e48c18a7c1
parent 604034 04b2345e86409f823e089bb44b59fd7e278b0097
child 604036 84580a18f7004d023fe9666a0f01c1b97b03c355
child 604039 e7fb8fc6cb2338cfc4043a994b575e2559abde62
push id39133
push userctuns@mozilla.com
push dateMon, 10 Jan 2022 09:37:02 +0000
treeherdermozilla-central@b81970e39db4 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersbomsy
bugs1747815
milestone97.0a1
first release with
nightly linux32
b81970e39db4 / 97.0a1 / 20220110093702 / files
nightly linux64
b81970e39db4 / 97.0a1 / 20220110093702 / files
nightly mac
b81970e39db4 / 97.0a1 / 20220110093702 / files
nightly win32
b81970e39db4 / 97.0a1 / 20220110093702 / files
nightly win64
b81970e39db4 / 97.0a1 / 20220110093702 / files
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
releases
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1747815 - [devtools] Document sources and source-actors reducers. r=bomsy Differential Revision: https://phabricator.services.mozilla.com/D134752
devtools/client/debugger/src/reducers/source-actors.js
devtools/client/debugger/src/reducers/sources.js
--- a/devtools/client/debugger/src/reducers/source-actors.js
+++ b/devtools/client/debugger/src/reducers/source-actors.js
@@ -13,24 +13,35 @@ import {
   getMappedResource,
   makeWeakQuery,
   makeIdQuery,
   makeReduceAllQuery,
 } from "../utils/resource";
 
 import { asyncActionAsValue } from "../actions/utils/middleware/promise";
 
+/**
+ * This reducer stores the list of all source actors.
+ * There is a one-one relationship with Source Actors from the server codebase,
+ * as well as SOURCE Resources distributed by the ResourceCommand API.
+ *
+ * See create.js: `createSourceActor` for the shape of the source actor objects.
+ * This reducer will append the following attributes:
+ * - breakableLines: { state: <"pending"|"fulfilled">, value: Array<Number> }
+ *   List of all lines where breakpoints can be set
+ * - breakpointPositions: Map<line, { state: <"pending"|"fulfilled">, value: Array<Number> }>
+ *   Map of the column positions per line where breakpoints can be set
+ */
 export const initial = createInitial();
 
 export default function update(state = initial, action) {
   switch (action.type) {
     case "INSERT_SOURCE_ACTORS": {
       const { items } = action;
-      // The `item` objects are defined from `newGeneratedSources` action:
-      // https://searchfox.org/mozilla-central/rev/4646b826a25d3825cf209db890862b45fa09ffc3/devtools/client/debugger/src/actions/sources/newSources.js#300-314
+      // The `item` objects are defined from create.js: `createSource` method.
       state = insertResources(
         state,
         items.map(item => ({
           ...item,
           breakpointPositions: new Map(),
           breakableLines: null,
         }))
       );
--- a/devtools/client/debugger/src/reducers/sources.js
+++ b/devtools/client/debugger/src/reducers/sources.js
@@ -51,30 +51,110 @@ import {
   getSourceActors,
   getAllThreadsBySource,
   getBreakableLinesForSourceActors,
 } from "./source-actors";
 import { getAllThreads } from "./threads";
 
 export function initialSourcesState(state) {
   return {
+    /**
+     * All currently available sources.
+     *
+     * See create.js: `createSourceObject` method for the description of stored objects.
+     * This reducers will add an extra `content` attribute which is the source text for each source.
+     */
     sources: createInitial(),
+
+    /**
+     * All sources associated with a given URL. When using source maps, multiple
+     * sources can have the same URL.
+     *
+     * Dictionary(url => array<source id>)
+     */
     urls: {},
+
+    /**
+     * All full URLs belonging to a given plain (query string stripped) URL.
+     * Query strings are only shown in the Sources tab if they are required for
+     * disambiguation.
+     *
+     * Dictionary(plain url => array<source url>)
+     */
     plainUrls: {},
+
+    /**
+     * List of all source ids whose source has a url attribute defined
+     *
+     * Array<source id>
+     */
     sourcesWithUrls: [],
-    content: {},
+
+    /**
+     * Mapping of source id's to one or more source-actor id's.
+     * Dictionary whose keys are source id's and values are arrays
+     * made of all the related source-actor id's.
+     *
+     * "source" are the objects stored in this reducer, in the `sources` attribute.
+     * "source-actor" are the objects stored in the "source-actors.js" reducer, in its `sourceActors` attribute.
+     *
+     * Dictionary(source id => array<SourceActor ID>)
+     */
     actors: {},
+
     breakpointPositions: {},
     breakableLines: {},
+
+    /**
+     * Incremental number that is bumped each time we navigate to a new page.
+     *
+     * This is used to better handle async race condition where we mix previous page data
+     * with the new page. As sources are keyed by URL we may easily conflate the two page loads data.
+     */
     epoch: 1,
+
+    /**
+     * The actual currently selected location.
+     * Only set if the related source is already registered in the sources reducer.
+     * Otherwise, pendingSelectedLocation should be used. Typically for sources
+     * which are about to be created.
+     *
+     * It also includes line and column information.
+     *
+     * See `createLocation` for the definition of this object.
+     */
     selectedLocation: undefined,
+
+    /**
+     * When we want to select a source that isn't available yet, use this.
+     * The location object should have a url attribute instead of a sourceId.
+     */
     pendingSelectedLocation: prefs.pendingSelectedLocation,
+
+    /**
+     * Project root set from the Source Tree.
+     *
+     * This focused the source tree on a subset of sources.
+     * `relativeUrl` attribute of all sources will be updated according
+     * to the new root.
+     */
     projectDirectoryRoot: prefs.projectDirectoryRoot,
     projectDirectoryRootName: prefs.projectDirectoryRootName,
+
+    /**
+     * Boolean, to be set to true in order to display WebExtension's content scripts
+     * that are applied to the current page we are debugging.
+     *
+     * Covered by: browser_dbg-content-script-sources.js
+     * Bound to: devtools.chrome.enabled
+     *
+     * boolean
+     */
     chromeAndExtensionsEnabled: prefs.chromeAndExtensionsEnabled,
+
     /* FORMAT:
      * blackboxedRanges: {
      *  [source url]: [range, range, ...], -- source lines blackboxed
      *  [source url]: [], -- whole source blackboxed
      *  ...
      * }
      */
     blackboxedRanges: state?.blackboxedRanges ?? {},