diff --git a/src/decoration.js b/src/decoration.js index 1263259c8..d2ce9203e 100644 --- a/src/decoration.js +++ b/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} diff --git a/src/grammar-registry.js b/src/grammar-registry.js index 85d556f2a..33eba9785 100644 --- a/src/grammar-registry.js +++ b/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: diff --git a/src/pane.js b/src/pane.js index a55575ae0..c7e4749d0 100644 --- a/src/pane.js +++ b/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 Ctrl) is lifted. moveActiveItemToTopOfStack() { delete this.itemStackIndex; this.addItemToStack(this.activeItem); diff --git a/src/wasm-tree-sitter-grammar.js b/src/wasm-tree-sitter-grammar.js index 076be6661..8ecdf9ada 100644 --- a/src/wasm-tree-sitter-grammar.js +++ b/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]