Modify some AtomDoc blocks…

…in anticipation of the new auto-generated API docs. (These are some tweaks that I've applied locally because they make the docs better.)

src/decoration.js

@@ -3,7 +3,7 @@ const { Emitter } = require('event-kit');
 let idCounter = 0;
 const nextId = () => idCounter++;
 
-const normalizeDecorationProperties = function(decoration, decorationParams) {
+const normalizeDecorationProperties = function (decoration, decorationParams) {
   decorationParams.id = decoration.id;
 
   if (
@@ -117,7 +117,7 @@ module.exports = class Decoration {
   Section: Event Subscription
   */
 
-  // Essential: When the {Decoration} is updated via {Decoration::update}.
+  // Essential: When the {Decoration} is updated via {Decoration::setProperties}.
   //
   // * `callback` {Function}
   //   * `event` {Object}

src/grammar-registry.js

@@ -259,8 +259,20 @@ module.exports = class GrammarRegistry {
     return useLegacyTreeSitter ? 'node-tree-sitter' : 'wasm-tree-sitter';
   }
 
-  // Extended: Returns a {Number} representing how well the grammar matches the
-  // `filePath` and `contents`.
+  // Extended: Evaluates a grammar's fitness for use for a certain file.
+  //
+  // By analyzing the file's extension and contents — plus other criteria, like
+  // the user's configuration — Pulsar will assign a score to this grammar that
+  // represents how suitable it is for the given file.
+  //
+  // Ultimately, whichever grammar scores highest for this file will be used
+  // to highlight it.
+  //
+  // * `grammar`: A given {Grammar}.
+  // * `filePath`: A {String} path to the file.
+  // * `contents`: The {String} contents of the file.
+  //
+  // Returns a {Number}.
   getGrammarScore(grammar, filePath, contents) {
     if (contents == null && fs.isFileSync(filePath)) {
       contents = fs.readFileSync(filePath, 'utf8');
@@ -305,8 +317,8 @@ module.exports = class GrammarRegistry {
         }
       }
 
-      // Prefer grammars with matching content regexes. Prefer a grammar with no content regex
-      // over one with a non-matching content regex.
+      // Prefer grammars with matching content regexes. Prefer a grammar with
+      // no content regex over one with a non-matching content regex.
       if (grammar.contentRegex) {
         const contentMatch = isTreeSitter
           ? grammar.contentRegex.test(contents)
@@ -318,7 +330,8 @@ module.exports = class GrammarRegistry {
         }
       }
 
-      // Prefer grammars that the user has manually installed over bundled grammars.
+      // Prefer grammars that the user has manually installed over bundled
+      // grammars.
       if (!grammar.bundledPackage) score += 0.01;
     }
 
@@ -544,7 +557,7 @@ module.exports = class GrammarRegistry {
     return disposable;
   }
 
-  // Experimental: Specify a type of syntax node that may embed other languages.
+  // Public: Specify a type of syntax node that may embed other languages.
   //
   // * `grammarId` The {String} id of the parent language
   // * `injectionPoint` An {Object} with the following keys:

src/pane.js

@@ -191,14 +191,14 @@ module.exports = class Pane {
   Section: Event Subscription
   */
 
-  // Public: Invoke the given callback when the pane resizes
+  // Public: Invoke the given callback when the pane resizes.
   //
-  // The callback will be invoked when pane's flexScale property changes.
+  // The callback will be invoked when pane's `flexScale` property changes.
   // Use {::getFlexScale} to get the current value.
   //
-  // * `callback` {Function} to be called when the pane is resized
-  //   * `flexScale` {Number} representing the panes `flex-grow`; ability for a
-  //     flex item to grow if necessary.
+  // * `callback` {Function} to be called when the pane is resized.
+  //   * `flexScale` {Number} representing the pane's `flex-grow`; ability for
+  //     a flex item to grow if necessary.
   //
   // Returns a {Disposable} on which '.dispose()' can be called to unsubscribe.
   onDidChangeFlexScale(callback) {
@@ -508,7 +508,7 @@ module.exports = class Pane {
     return this.items[index];
   }
 
-  // Makes the next item in the itemStack active.
+  // Public: Makes the next item in the itemStack active.
   activateNextRecentlyUsedItem() {
     if (this.items.length > 1) {
       if (this.itemStackIndex == null)
@@ -522,7 +522,7 @@ module.exports = class Pane {
     }
   }
 
-  // Makes the previous item in the itemStack active.
+  // Public: Makes the previous item in the itemStack active.
   activatePreviousRecentlyUsedItem() {
     if (this.items.length > 1) {
       if (
@@ -538,7 +538,8 @@ module.exports = class Pane {
     }
   }
 
-  // Moves the active item to the end of the itemStack once the ctrl key is lifted
+  // Public: Moves the active item to the end of the item stack once a modifier
+  // key (typically <kbd>Ctrl</kbd>) is lifted.
   moveActiveItemToTopOfStack() {
     delete this.itemStackIndex;
     this.addItemToStack(this.activeItem);

src/wasm-tree-sitter-grammar.js

@@ -121,15 +121,18 @@ module.exports = class WASMTreeSitterGrammar {
     return this.scopeNamesById.get(id);
   }
 
-  // Returns the Tree-sitter language instance associated with this grammar
-  // _if_ it has already loaded. Call this only when you can be certain that
-  // it's present.
+  // Extended: Retrieves the Tree-sitter `Language` instance associated with
+  // this grammar _if_ it has already been loaded.
+  //
+  // Language instances cannot be retrieved synchrously, so this will return
+  // `undefined` if the instance has not yet been loaded. In that case, going
+  // async will be unavoidable, and you’ll need to call {::getLanguage}.
   getLanguageSync() {
     return this._language;
   }
 
-  // Extended: Returns the Tree-sitter language instance associated with this
-  // grammar once it loads.
+  // Extended: Retrieves the Tree-sitter language instance associated with this
+  // grammar.
   //
   // Returns a {Promise} that will resolve with a Tree-sitter `Language`
   // instance. Once it resolves, the grammar is ready to perform parsing and to
@@ -355,6 +358,11 @@ module.exports = class WASMTreeSitterGrammar {
 
   // Extended: Calls `callback` when any of this grammar's query files change.
   //
+  // Since a grammar’s query files won’t change during ordinary operation, this
+  // method’s main purpose is to aid the development of grammars by applying
+  // changes to query files in real time. This happens automatically when
+  // Pulsar is running in dev mode.
+  //
   // The callback is invoked with an object argument with two keys:
   //
   // * `callback`: The callback to be invoked. Takes one argument:
@@ -389,6 +397,10 @@ module.exports = class WASMTreeSitterGrammar {
   // This differs from TextMate-style injections, which operate at the scope
   // level and are currently incompatible with Tree-sitter grammars.
   //
+  // You should typically not call this method directly; instead, call
+  // {GrammarRegistry::addInjectionPoint} and pass a given grammar’s root
+  // language scope as the first argument.
+  //
   // NOTE: Packages will call {::addInjectionPoint} with a given scope name,
   // and that call will be delegated to any Tree-sitter grammars that match
   // that scope name, whether they're legacy Tree-sitter or modern Tree-sitter.
@@ -439,7 +451,6 @@ module.exports = class WASMTreeSitterGrammar {
   //     applied varies based on the grammar; the function will be called with
   //     a grammar instance as its only argument.
   //
-  //
   addInjectionPoint(injectionPoint) {
     let { type } = injectionPoint;
     let injectionPoints = this.injectionPointsByType[type];
@@ -468,15 +479,15 @@ module.exports = class WASMTreeSitterGrammar {
   Section - Backward compatibility shims
   */
   /* eslint-disable no-unused-vars */
-  onDidUpdate(callback) {
+  onDidUpdate(_callback) {
     // do nothing
   }
 
-  tokenizeLines(text, compatibilityMode = true) {
+  tokenizeLines(text, _compatibilityMode = true) {
     return text.split('\n').map(line => this.tokenizeLine(line, null, false));
   }
 
-  tokenizeLine(line, ruleStack, firstLine) {
+  tokenizeLine(line, _ruleStack, _firstLine) {
     return {
       value: line,
       scopes: [this.scopeName]