Bug 1471272 - Add [SMDOC] tags for in-source documentation. r=jandem,nbp

moztcampbell · moztcampbell · commit ab67c3fb817e · 2018-06-28T15:23:25.000-04:00
MozReview-Commit-ID: I038aYgvwe4
diff --git a/js/public/CallArgs.h b/js/public/CallArgs.h
@@ -5,6 +5,8 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 /*
+ * [SMDOC] JS::CallArgs API
+ *
  * Helper classes encapsulating access to the callee, |this| value, arguments,
  * and argument count for a call/construct operation.
  *
@@ -46,10 +48,7 @@
  *
  * It's possible (albeit deprecated) to manually index into |vp| to access the
  * callee, |this|, and arguments of a function, and to set its return value.
- * It's also possible to use the supported API of JS_CALLEE, JS_THIS, JS_ARGV,
- * JS_RVAL, and JS_SET_RVAL to the same ends.
- *
- * But neither API has the error-handling or moving-GC correctness of CallArgs.
+ * This does not have the error-handling or moving-GC correctness of CallArgs.
  * New code should use CallArgs instead whenever possible.
  *
  * The eventual plan is to change JSNative to take |const CallArgs&| directly,
diff --git a/js/public/Debug.h b/js/public/Debug.h
@@ -27,6 +27,8 @@ class Debugger;
 namespace JS {
 namespace dbg {
 
+// [SMDOC] Debugger builder API
+//
 // Helping embedding code build objects for Debugger
 // -------------------------------------------------
 //
diff --git a/js/public/Proxy.h b/js/public/Proxy.h
@@ -37,6 +37,8 @@ class RegExpShared;
 class JS_FRIEND_API(Wrapper);
 
 /*
+ * [SMDOC] Proxy Objects
+ *
  * A proxy is a JSObject with highly customizable behavior. ES6 specifies a
  * single kind of proxy, but the customization mechanisms we use to implement
  * ES6 Proxy objects are also useful wherever an object with weird behavior is
diff --git a/js/public/Result.h b/js/public/Result.h
@@ -5,6 +5,8 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 /*
+ * [SMDOC] JS::Result
+ *
  * `Result` is used as the return type of many SpiderMonkey functions that
  * can either succeed or fail. See "/mfbt/Result.h".
  *
diff --git a/js/public/RootingAPI.h b/js/public/RootingAPI.h
@@ -28,6 +28,8 @@
 #include "js/Utility.h"
 
 /*
+ * [SMDOC] Stack Rooting
+ *
  * Moving GC Stack Rooting
  *
  * A moving GC may change the physical location of GC allocated things, even
diff --git a/js/public/UbiNode.h b/js/public/UbiNode.h
@@ -29,7 +29,7 @@
 #include "js/Value.h"
 #include "js/Vector.h"
 
-// JS::ubi::Node
+// [SMDOC] ubi::Node (Heap Analysis framework)
 //
 // JS::ubi::Node is a pointer-like type designed for internal use by heap
 // analysis tools. A ubi::Node can refer to:
diff --git a/js/public/Value.h b/js/public/Value.h
@@ -268,6 +268,8 @@ CanonicalizeNaN(double d)
 }
 
 /**
+ * [SMDOC] JS::Value type
+ *
  * JS::Value is the interface for a single JavaScript Engine value.  A few
  * general notes on JS::Value:
  *
diff --git a/js/src/builtin/TypedObject.h b/js/src/builtin/TypedObject.h
@@ -18,7 +18,7 @@
 
 /*
  * -------------
- * Typed Objects
+ * [SMDOC] Typed Objects
  * -------------
  *
  * Typed objects are a special kind of JS object where the data is
diff --git a/js/src/frontend/Parser.h b/js/src/frontend/Parser.h
@@ -10,6 +10,8 @@
 #define frontend_Parser_h
 
 /*
+ * [SMDOC] JS Parser
+ *
  * JS parsers capable of generating ASTs from source text.
  *
  * A parser embeds token stream information, then gets and matches tokens to
diff --git a/js/src/frontend/TokenStream.h b/js/src/frontend/TokenStream.h
@@ -16,6 +16,8 @@
 #define frontend_TokenStream_h
 
 /*
+ * [SMDOC] Parser Token Stream
+ *
  * A token stream exposes the raw tokens -- operators, names, numbers,
  * keywords, and so on -- of JavaScript source code.
  *
diff --git a/js/src/gc/AtomMarking.cpp b/js/src/gc/AtomMarking.cpp
@@ -15,7 +15,7 @@
 namespace js {
 namespace gc {
 
-// Atom Marking Overview
+// [SMDOC] GC Atom Marking
 //
 // Things in the atoms zone (which includes atomized strings and other things,
 // all of which we will refer to as 'atoms' here) may be pointed to freely by
diff --git a/js/src/gc/Barrier.h b/js/src/gc/Barrier.h
@@ -17,6 +17,8 @@
 #include "js/Value.h"
 
 /*
+ * [SMDOC] GC Barriers
+ *
  * A write barrier is a mechanism used by incremental or generation GCs to
  * ensure that every value that needs to be marked is marked. In general, the
  * write barrier should be invoked whenever a write can cause the set of things
diff --git a/js/src/gc/GC.cpp b/js/src/gc/GC.cpp
@@ -5,6 +5,8 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 /*
+ * [SMDOC] Garbage Collector
+ *
  * This code implements an incremental mark-and-sweep garbage collector, with
  * most sweeping carried out in the background on a parallel thread.
  *
diff --git a/js/src/gc/Marking.cpp b/js/src/gc/Marking.cpp
@@ -54,6 +54,8 @@ using mozilla::IsBaseOf;
 using mozilla::IsSame;
 using mozilla::PodCopy;
 
+// [SMDOC] GC Tracing
+//
 // Tracing Overview
 // ================
 //
diff --git a/js/src/gc/Scheduling.h b/js/src/gc/Scheduling.h
@@ -5,6 +5,8 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 /*
+ * [SMDOC] GC Scheduling
+ *
  * GC Scheduling Overview
  * ======================
  *
diff --git a/js/src/gc/Zone.h b/js/src/gc/Zone.h
@@ -99,6 +99,8 @@ class MOZ_NON_TEMPORARY_CLASS FunctionToStringCache
 
 namespace JS {
 
+// [SMDOC] GC Zones
+//
 // A zone is a collection of compartments. Every compartment belongs to exactly
 // one zone. In Firefox, there is roughly one zone per tab along with a system
 // zone for everything else. Zones mainly serve as boundaries for garbage
diff --git a/js/src/irregexp/RegExpEngine.cpp b/js/src/irregexp/RegExpEngine.cpp
@@ -1326,6 +1326,7 @@ Analysis::VisitAssertion(AssertionNode* that)
     EnsureAnalyzed(that->on_success());
 }
 
+// [SMDOC] Irregexp internals
 // -------------------------------------------------------------------
 // Implementation of the Irregexp regular expression engine.
 //
diff --git a/js/src/jit/AliasAnalysis.cpp b/js/src/jit/AliasAnalysis.cpp
@@ -116,6 +116,8 @@ IonSpewAliasInfo(const char* pre, MInstruction* ins, const char* post)
 #endif
 }
 
+// [SMDOC] IonMonkey Alias Analysis
+//
 // This pass annotates every load instruction with the last store instruction
 // on which it depends. The algorithm is optimistic in that it ignores explicit
 // dependencies and only considers loads and stores.
diff --git a/js/src/jit/AtomicOperations.h b/js/src/jit/AtomicOperations.h
@@ -15,6 +15,8 @@ namespace js {
 namespace jit {
 
 /*
+ * [SMDOC] Atomic Operations
+ *
  * The atomic operations layer defines types and functions for
  * JIT-compatible atomic operation.
  *
diff --git a/js/src/jit/Bailouts.h b/js/src/jit/Bailouts.h
@@ -16,8 +16,10 @@
 namespace js {
 namespace jit {
 
-// A "bailout" is a condition in which we need to recover an interpreter frame
-// from an IonFrame. Bailouts can happen for the following reasons:
+// [SMDOC] IonMonkey Bailouts
+//
+// A "bailout" is a condition in which we need to recover a baseline frame from
+// an IonFrame. Bailouts can happen for the following reasons:
 //   (1) A deoptimization guard, for example, an add overflows or a type check
 //       fails.
 //   (2) A check or assumption held by the JIT is invalidated by the VM, and
@@ -36,7 +38,7 @@ namespace jit {
 //  jmp _bailout
 //
 // The bailout target needs to somehow translate the Ion frame (whose state
-// will differ at each program point) to an interpreter frame. This state is
+// will differ at each program point) to a baseline frame. This state is
 // captured into the IonScript's snapshot buffer, and for each bailout we know
 // which snapshot corresponds to its state.
 //
@@ -49,7 +51,7 @@ namespace jit {
 //       to find the structure of the frame, and then use the stack and spilled
 //       registers to perform frame conversion.
 //   (5) Bailout() returns, and the JIT must immediately return to the
-//       interpreter (all frames are converted at once).
+//       baseline JIT code (all frames are converted at once).
 //
 // (2) and (3) are implemented by a trampoline held in the compartment.
 // Naively, we could implement (1) like:
diff --git a/js/src/jit/CacheIR.cpp b/js/src/jit/CacheIR.cpp
@@ -625,7 +625,7 @@ GeneratePrototypeGuards(CacheIRWriter& writer, JSObject* obj, JSObject* holder,
     // [[GetOwnProperty]] has no definition of the target property.
     //
     //
-    // Shape Teleporting Optimization
+    // [SMDOC] Shape Teleporting Optimization
     // ------------------------------
     //
     // Starting with the assumption (and guideline to developers) that mutating
diff --git a/js/src/jit/CacheIR.h b/js/src/jit/CacheIR.h
@@ -22,6 +22,8 @@ namespace jit {
 
 enum class BaselineCacheIRStubKind;
 
+// [SMDOC] CacheIR
+//
 // CacheIR is an (extremely simple) linear IR language for inline caches.
 // From this IR, we can generate machine code for Baseline or Ion IC stubs.
 //
diff --git a/js/src/jit/MacroAssembler.h b/js/src/jit/MacroAssembler.h
@@ -41,6 +41,8 @@
 #include "vm/TypedArrayObject.h"
 #include "vm/UnboxedObject.h"
 
+// [SMDOC] MacroAssembler multi-platform overview
+//
 // * How to read/write MacroAssembler method declarations:
 //
 // The following macros are made to avoid #ifdef around each method declarations
diff --git a/js/src/jit/RangeAnalysis.cpp b/js/src/jit/RangeAnalysis.cpp
@@ -37,6 +37,8 @@ using mozilla::Swap;
 using JS::GenericNaN;
 using JS::ToInt32;
 
+// [SMDOC] IonMonkey Range Analysis
+//
 // This algorithm is based on the paper "Eliminating Range Checks Using
 // Static Single Assignment Form" by Gough and Klaren.
 //
diff --git a/js/src/jit/Recover.h b/js/src/jit/Recover.h
@@ -17,6 +17,8 @@
 namespace js {
 namespace jit {
 
+// [SMDOC] IonMonkey Recover Instructions
+//
 // This file contains all recover instructions.
 //
 // A recover instruction is an equivalent of a MIR instruction which is executed
diff --git a/js/src/jit/RegisterSets.h b/js/src/jit/RegisterSets.h
@@ -466,6 +466,8 @@ class RegisterSet {
     }
 };
 
+// [SMDOC] JIT Register-Set overview
+//
 // There are 2 use cases for register sets:
 //
 //   1. To serve as a pool of allocatable register. This is useful for working
@@ -504,6 +506,8 @@ class AllocatableSet;
 template <typename RegisterSet>
 class LiveSet;
 
+// [SMDOC] JIT Register-Set (Allocatable)
+//
 // Base accessors classes have the minimal set of raw methods to manipulate the register set
 // given as parameter in a consistent manner.  These methods are:
 //
@@ -620,6 +624,8 @@ class AllocatableSetAccessors<RegisterSet>
 };
 
 
+// [SMDOC] JIT Register-Set (Live)
+//
 // The LiveSet accessors are used to collect a list of allocated
 // registers. Taking or adding a register should *not* consider the aliases, as
 // we care about interpreting the registers with the correct type.  For example,
diff --git a/js/src/jit/SharedIC.h b/js/src/jit/SharedIC.h
@@ -22,6 +22,7 @@
 namespace js {
 namespace jit {
 
+// [SMDOC] JIT Inline Caches (ICs)
 //
 // Baseline Inline Caches are polymorphic caches that aggressively
 // share their stub code.
diff --git a/js/src/jit/Snapshots.cpp b/js/src/jit/Snapshots.cpp
@@ -19,6 +19,8 @@
 using namespace js;
 using namespace js::jit;
 
+// [SMDOC] IonMonkey Snapshot encoding
+//
 // Encodings:
 //   [ptr] A fixed-size pointer.
 //   [vwu] A variable-width unsigned integer.
diff --git a/js/src/jit/ValueNumbering.cpp b/js/src/jit/ValueNumbering.cpp
@@ -15,6 +15,8 @@ using namespace js;
 using namespace js::jit;
 
 /*
+ * [SMDOC] IonMonkey Value Numbering
+ *
  * Some notes on the main algorithm here:
  *  - The SSA identifier id() is the value number. We do replaceAllUsesWith as
  *    we go, so there's always at most one visible value with a given number.
diff --git a/js/src/jit/shared/IonAssemblerBufferWithConstantPools.h b/js/src/jit/shared/IonAssemblerBufferWithConstantPools.h
@@ -14,6 +14,8 @@
 #include "jit/JitSpewer.h"
 #include "jit/shared/IonAssemblerBuffer.h"
 
+// [SMDOC] JIT AssemblerBuffer constant pooling (ARM/ARM64/MIPS)
+//
 // This code extends the AssemblerBuffer to support the pooling of values loaded
 // using program-counter relative addressing modes. This is necessary with the
 // ARM instruction set because it has a fixed instruction size that can not
diff --git a/js/src/threading/ExclusiveData.h b/js/src/threading/ExclusiveData.h
@@ -17,6 +17,8 @@
 namespace js {
 
 /**
+ * [SMDOC] ExclusiveData API
+ *
  * A mutual exclusion lock class.
  *
  * `ExclusiveData` provides an RAII guard to automatically lock and unlock when
diff --git a/js/src/vm/ArgumentsObject.h b/js/src/vm/ArgumentsObject.h
@@ -98,6 +98,8 @@ struct ArgumentsData
 static const unsigned ARGS_LENGTH_MAX = 500 * 1000;
 
 /*
+ * [SMDOC] ArgumentsObject
+ *
  * ArgumentsObject instances represent |arguments| objects created to store
  * function arguments when a function is called.  It's expensive to create such
  * objects if they're never used, so they're only created when they are
diff --git a/js/src/vm/ArrayBufferObject.cpp b/js/src/vm/ArrayBufferObject.cpp
@@ -592,6 +592,8 @@ ArrayBufferObject::changeContents(JSContext* cx, BufferContents newContents,
 }
 
 /*
+ * [SMDOC] WASM Linear Memory structure
+ *
  * Wasm Raw Buf Linear Memory Structure
  *
  * The linear heap in Wasm is an mmaped array buffer. Several
diff --git a/js/src/vm/BytecodeUtil.h b/js/src/vm/BytecodeUtil.h
@@ -35,7 +35,7 @@ FOR_EACH_OPCODE(ENUMERATE_OPCODE)
 } JSOp;
 
 /*
- * JS bytecode formats.
+ * [SMDOC] Bytecode Format flags (JOF_*)
  */
 enum {
     JOF_BYTE            = 0,        /* single bytecode, no immediates */
diff --git a/js/src/vm/EnvironmentObject.h b/js/src/vm/EnvironmentObject.h
@@ -45,6 +45,8 @@ EnvironmentCoordinateFunctionScript(JSScript* script, jsbytecode* pc);
 /*** Environment objects *****************************************************/
 
 /*
+ * [SMDOC] Environment Objects
+ *
  * About environments
  * ------------------
  *
diff --git a/js/src/vm/JSObject.h b/js/src/vm/JSObject.h
@@ -49,6 +49,8 @@ bool SetImmutablePrototype(JSContext* cx, JS::HandleObject obj, bool* succeeded)
 }  /* namespace js */
 
 /*
+ * [SMDOC] JSObject layout
+ *
  * A JavaScript object.
  *
  * This is the base class for all objects exposed to JS script (as well as some
diff --git a/js/src/vm/JSScript.cpp b/js/src/vm/JSScript.cpp
@@ -2332,6 +2332,8 @@ ScriptSource::setSourceMapURL(JSContext* cx, const char16_t* sourceMapURL)
 }
 
 /*
+ * [SMDOC] JSScript data layout (shared)
+ *
  * Shared script data management.
  *
  * SharedScriptData::data contains data that can be shared within a
@@ -2505,6 +2507,8 @@ js::FreeScriptData(JSRuntime* rt)
 }
 
 /*
+ * [SMDOC] JSScript data layout (unshared)
+ *
  * JSScript::data and SharedScriptData::data have complex,
  * manually-controlled, memory layouts.
  *
diff --git a/js/src/vm/NativeObject.h b/js/src/vm/NativeObject.h
diff --git a/js/src/vm/ObjectGroup.h b/js/src/vm/ObjectGroup.h
diff --git a/js/src/vm/Opcodes.h b/js/src/vm/Opcodes.h
diff --git a/js/src/vm/Realm.h b/js/src/vm/Realm.h
diff --git a/js/src/vm/Runtime.h b/js/src/vm/Runtime.h
diff --git a/js/src/vm/Shape.h b/js/src/vm/Shape.h
diff --git a/js/src/vm/Stack.h b/js/src/vm/Stack.h
diff --git a/js/src/vm/StringType.h b/js/src/vm/StringType.h
diff --git a/js/src/vm/SymbolType.h b/js/src/vm/SymbolType.h
diff --git a/js/src/vm/TypeInference.h b/js/src/vm/TypeInference.h
diff --git a/js/src/wasm/WasmBaselineCompile.cpp b/js/src/wasm/WasmBaselineCompile.cpp

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,8 @@`
`5`	`5`	`* file, You can obtain one at http://mozilla.org/MPL/2.0/. */`
`6`	`6`
`7`	`7`	`/*`
	`8`	`+ * [SMDOC] JS::CallArgs API`
	`9`	`+ *`
`8`	`10`	`* Helper classes encapsulating access to the callee, \|this\| value, arguments,`
`9`	`11`	`* and argument count for a call/construct operation.`
`10`	`12`	`*`
`@@ -46,10 +48,7 @@`
`46`	`48`	`*`
`47`	`49`	`* It's possible (albeit deprecated) to manually index into \|vp\| to access the`
`48`	`50`	`* callee, \|this\|, and arguments of a function, and to set its return value.`
`49`		`- * It's also possible to use the supported API of JS_CALLEE, JS_THIS, JS_ARGV,`
`50`		`- * JS_RVAL, and JS_SET_RVAL to the same ends.`
`51`		`- *`
`52`		`- * But neither API has the error-handling or moving-GC correctness of CallArgs.`
	`51`	`+ * This does not have the error-handling or moving-GC correctness of CallArgs.`
`53`	`52`	`* New code should use CallArgs instead whenever possible.`
`54`	`53`	`*`
`55`	`54`	`* The eventual plan is to change JSNative to take \|const CallArgs&\| directly,`
Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,8 @@`
`28`	`28`	`#include "js/Utility.h"`
`29`	`29`
`30`	`30`	`/*`
	`31`	`+ * [SMDOC] Stack Rooting`
	`32`	`+ *`
`31`	`33`	`* Moving GC Stack Rooting`
`32`	`34`	`*`
`33`	`35`	`* A moving GC may change the physical location of GC allocated things, even`
Original file line number	Diff line number	Diff line change
`@@ -268,6 +268,8 @@ CanonicalizeNaN(double d)`
`268`	`268`	`}`
`269`	`269`
`270`	`270`	`/**`
	`271`	`+ * [SMDOC] JS::Value type`
	`272`	`+ *`
`271`	`273`	`* JS::Value is the interface for a single JavaScript Engine value. A few`
`272`	`274`	`* general notes on JS::Value:`
`273`	`275`	`*`
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@`
`18`	`18`
`19`	`19`	`/*`
`20`	`20`	`* -------------`
`21`		`- * Typed Objects`
	`21`	`+ * [SMDOC] Typed Objects`
`22`	`22`	`* -------------`
`23`	`23`	`*`
`24`	`24`	`* Typed objects are a special kind of JS object where the data is`
Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,8 @@`
`10`	`10`	`#define frontend_Parser_h`
`11`	`11`
`12`	`12`	`/*`
	`13`	`+ * [SMDOC] JS Parser`
	`14`	`+ *`
`13`	`15`	`* JS parsers capable of generating ASTs from source text.`
`14`	`16`	`*`
`15`	`17`	`* A parser embeds token stream information, then gets and matches tokens to`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,8 @@`
`16`	`16`	`#define frontend_TokenStream_h`
`17`	`17`
`18`	`18`	`/*`
	`19`	`+ * [SMDOC] Parser Token Stream`
	`20`	`+ *`
`19`	`21`	`* A token stream exposes the raw tokens -- operators, names, numbers,`
`20`	`22`	`* keywords, and so on -- of JavaScript source code.`
`21`	`23`	`*`