Skip to content

Commit

Permalink
Docs: improve jsdoc, better for typings (#182)
Browse files Browse the repository at this point in the history
* Docs: improve jsdoc, better for typings

* docs: improve jsdoc without @types/*
  • Loading branch information
JounQin authored Mar 30, 2021
1 parent 79be776 commit 1280ac1
Showing 1 changed file with 25 additions and 3 deletions.
28 changes: 25 additions & 3 deletions lib/processor.js
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,25 @@
* @author Brandon Mills
*/

/**
* @typedef {import('eslint/lib/shared/types').LintMessage} Message
*
* @typedef {Object} ASTNode
* @property {string} type
* @property {string} [lang]
*
* @typedef {Object} RangeMap
* @property {number} js
* @property {number} md
*
* @typedef {Object} BlockBase
* @property {string} baseIndentText
* @property {string[]} comments
* @property {RangeMap[]} rangeMap
*
* @typedef {ASTNode & BlockBase} Block
*/

"use strict";

const unified = require("unified");
Expand All @@ -16,12 +35,15 @@ const SUPPORTS_AUTOFIX = true;

const markdown = unified().use(remarkParse);

/**
* @type {Block[]}
*/
let blocks = [];

/**
* Performs a depth-first traversal of the Markdown AST.
* @param {ASTNode} node A Markdown AST node.
* @param {Object} callbacks A map of node types to callbacks.
* @param {{[key: string]: (node: ASTNode) => void}} callbacks A map of node types to callbacks.
* @returns {void}
*/
function traverse(node, callbacks) {
Expand Down Expand Up @@ -120,7 +142,7 @@ function getIndentText(text, node) {
* @param {ASTNode} node A Markdown code block AST node.
* @param {string[]} comments List of configuration comment strings that will be
* inserted at the beginning of the code block.
* @returns {Object[]} A list of offset-based adjustments, where lookups are
* @returns {RangeMap[]} A list of offset-based adjustments, where lookups are
* done based on the `js` key, which represents the range in the linted JS,
* and the `md` key is the offset delta that, when added to the JS range,
* returns the corresponding location in the original Markdown source.
Expand Down Expand Up @@ -280,7 +302,7 @@ function preprocess(text) {
/**
* Creates a map function that adjusts messages in a code block.
* @param {Block} block A code block.
* @returns {Function} A function that adjusts messages in a code block.
* @returns {(message: Message) => Message} A function that adjusts messages in a code block.
*/
function adjustBlock(block) {
const leadingCommentLines = block.comments.reduce((count, comment) => count + comment.split("\n").length, 0);
Expand Down

0 comments on commit 1280ac1

Please sign in to comment.