From 1280ac1f4998e8ab2030742fe510cc02d200aea2 Mon Sep 17 00:00:00 2001
From: JounQin <admin@1stg.me>
Date: Tue, 30 Mar 2021 13:22:57 +0800
Subject: [PATCH] Docs: improve jsdoc, better for typings (#182)

* Docs: improve jsdoc, better for typings

* docs: improve jsdoc without @types/*
---
 lib/processor.js | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/lib/processor.js b/lib/processor.js
index 57428d6a..08085947 100644
--- a/lib/processor.js
+++ b/lib/processor.js
@@ -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");
@@ -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) {
@@ -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.
@@ -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);