feat: add JSDoc example

.gitignore

@@ -9,3 +9,4 @@ node_modules/
 /playwright-report/
 /playwright/.cache/
 $__StoryList.tid
+types/core/

bin/npm-publish.sh

@@ -4,4 +4,8 @@
 
 ./bin/clean.sh
 
+# Build typings
+npm i typescript
+npx tsc
+
 npm publish || exit 1

core/modules/parsers/base.js

@@ -0,0 +1,56 @@
+/**
+ * Represents an attribute in a parse tree node
+ * 
+ * @typedef {Object} ParseTreeAttribute
+ * @property {number} [end] - End position of attribute in source text
+ * @property {string} [name] - Name of attribute
+ * @property {number} [start] - Start position of attribute in source text
+ * @property {'string' | 'number' | 'bigint' | 'boolean' | 'macro' | 'macro-parameter'} type - Type of attribute
+ * @property {string | IMacroCallParseTreeNode} value - Actual value of attribute
+ */
+
+/**
+ * Base structure for a parse node
+ * 
+ * @typedef {Object} ParseTreeNode
+ * @property {string} type - Type of widget that will render this node
+ * @property {string} rule - Parse rule that generated this node. One rule can generate multiple types of nodes
+ * @property {number} start - Rule start marker in source text
+ * @property {number} end - Rule end marker in source text
+ * @property {Record<string,ParseTreeAttribute>} [attributes] - Attributes of widget
+ * @property {ParseTreeNode[]} [children] - Array of child parse nodes
+ */
+
+/**
+ * Base class for parsers. This only provides typing
+ * 
+ * @class
+ * @param {string} type - Content type of text to be parsed
+ * @param {string} text - Text to be parsed
+ * @param {Object} options - Parser options
+ * @param {boolean} [options.parseAsInline=false] - If true, text will be parsed as an inline run
+ * @param {Object} options.wiki - Reference to wiki store in use
+ * @param {string} [options._canonical_uri] - Optional URI of content if text is missing or empty
+ * @param {boolean} [options.configTrimWhiteSpace=false] - If true, parser trims white space
+ */
+function Parser(type, text, options) {
+  /**
+   * Result AST
+   * @type {ParseTreeNode[]}
+   */
+  this.tree = [];
+
+  /**
+   * Original text without modifications
+   * @type {string}
+   */
+  this.source = text;
+
+  /**
+   * Source content type in MIME format
+   * @type {string}
+   */
+  this.type = type;
+}
+
+exports.Parser = Parser;

core/modules/parsers/wikiparser/rules/codeblock.js

@@ -12,6 +12,27 @@ Wiki text rule for code blocks. For example:
 ```
 
 \*/
+
+/**
+ * @typedef {import("$:/core/modules/parsers/base.js").ParseTreeAttribute} ParseTreeAttribute
+ * @typedef {import('../wikirulebase.js').WikiRuleBase} WikiRuleBase
+ * @typedef {import('../../base.js').Parser} Parser
+ * @typedef {typeof exports & WikiRuleBase} ThisRule
+ */
+
+/**
+ * Represents the `codeblock` rule.
+ * 
+ * @typedef {Object} ParseTreeCodeblockNode
+ * @property {"codeblock"} rule
+ * @property {"codeblock"} type
+ * @property {number} start
+ * @property {number} end
+ * @property {Object} attributes
+ * @property {ParseTreeAttribute} attributes.code
+ * @property {ParseTreeAttribute} attributes.language
+ */
+
 (function(){
 
 /*jslint node: true, browser: true */
@@ -27,6 +48,12 @@ exports.init = function(parser) {
 	this.matchRegExp = /```([\w-]*)\r?\n/mg;
 };
 
+/**
+ * Parses the code block and returns an array of `codeblock` widgets.
+ * 
+ * @this {ThisRule}
+ * @returns {ParseTreeCodeblockNode[]} An array containing a single codeblock widget object.
+ */
 exports.parse = function() {
 	var reEnd = /(\r?\n```$)/mg;
 	var languageStart = this.parser.pos + 3,

core/modules/parsers/wikiparser/rules/html.js

@@ -17,6 +17,34 @@ This is a widget invocation
 }}}
 
 \*/
+
+
+/**
+ * @typedef {import("$:/core/modules/parsers/base.js").ParseTreeAttribute} ParseTreeAttribute
+ * @typedef {import('../wikirulebase.js').WikiRuleBase} WikiRuleBase
+ * @typedef {import('../../base.js').Parser} Parser
+ * @typedef {typeof exports & WikiRuleBase & {nextTag?:ParseTreeHtmlNode;}} ThisRule
+ */
+
+/**
+ * Represents the parser `html` rule
+ * 
+ * @typedef {Object} ParseTreeHtmlNode
+ * @property {"html"} rule
+ * @property {"element"} type
+ * @property {keyof HTMLElementTagNameMap} tag
+ * @property {number} start
+ * @property {number} end
+ * @property {Record<string,ParseTreeAttribute>} attributes - Contains attributes of HTML element
+ * @property {boolean} isSelfClosing - If tag is self-closing
+ * @property {boolean} isBlock - If tag is a block element
+ * @property {number} openTagStart
+ * @property {number} openTagEnd
+ * @property {number} closeTagStart
+ * @property {number} closeTagEnd
+ * @property {ParseTreeHtmlNode[]} [children]
+ */
+
 (function(){
 
 /*jslint node: true, browser: true */
@@ -26,10 +54,18 @@ This is a widget invocation
 exports.name = "html";
 exports.types = {inline: true, block: true};
 
+/**
+ * @param {Parser} parser 
+ */
 exports.init = function(parser) {
 	this.parser = parser;
 };
 
+/**
+ * @this {ThisRule}
+ * @param {number} startPos 
+ * @returns {number | undefined} Start position of next HTML tag
+ */
 exports.findNextMatch = function(startPos) {
 	// Find the next tag
 	this.nextTag = this.findNextTag(this.parser.source,startPos,{
@@ -38,11 +74,16 @@ exports.findNextMatch = function(startPos) {
 	return this.nextTag ? this.nextTag.start : undefined;
 };
 
-/*
-Parse the most recent match
-*/
+/**
+ * Parse most recent match
+ * @this {ThisRule}
+ * @returns {ParseTreeHtmlNode[]} Array containing parsed HTML tag object
+ */
 exports.parse = function() {
-	// Retrieve the most recent match so that recursive calls don't overwrite it
+	/**
+	 * @type {ParseTreeHtmlNode}
+	 * Retrieve the most recent match so that recursive calls don't overwrite it
+	 */
 	var tag = this.nextTag;
 	if (!tag.isSelfClosing) {
 		tag.openTagStart = tag.start;
@@ -161,6 +202,15 @@ exports.parseTag = function(source,pos,options) {
 	return node;
 };
 
+/**
+ * Find the next HTML tag in the source
+ * 
+ * @this {ThisRule}
+ * @param {string} source
+ * @param {number} pos - Position to start searching from
+ * @param {Object} options
+ * @returns {Object|null} Parsed tag object or null if no valid tag is found
+ */
 exports.findNextTag = function(source,pos,options) {
 	// A regexp for finding candidate HTML tags
 	var reLookahead = /<([a-zA-Z\-\$\.]+)/g;

core/modules/parsers/wikiparser/wikiparser.js

@@ -25,16 +25,18 @@ Attributes are stored as hashmaps of the following objects:
 /*global $tw: false */
 "use strict";
 
-/*
-type: content type of text
-text: text to be parsed
-options: see below:
-	parseAsInline: true to parse text as inline instead of block
-	wiki: reference to wiki to use
-	_canonical_uri: optional URI of content if text is missing or empty
-	configTrimWhiteSpace: true to trim whitespace
-*/
-var WikiParser = function(type,text,options) {
+/**
+ * @typedef {import('../base').Parser} Parser
+ */
+
+/**
+ * WikiParser class for parsing text of a specified MIME type.
+ * 
+ * @class
+ * @extends {Parser}
+ * @constructor
+ */
+function WikiParser(type,text,options) {
 	this.wiki = options.wiki;
 	var self = this;
 	// Check for an externally linked tiddler
@@ -99,8 +101,11 @@ var WikiParser = function(type,text,options) {
 	// Return the parse tree
 };
 
-/*
-*/
+/**
+ * Load a remote tiddler from a given URL.
+ * 
+ * @param {string} url - The URL of the remote tiddler to load.
+ */
 WikiParser.prototype.loadRemoteTiddler = function(url) {
 	var self = this;
 	$tw.utils.httpRequest({

core/modules/parsers/wikiparser/wikirulebase.js

@@ -12,22 +12,46 @@ Base class for wiki parser rules
 /*global $tw: false */
 "use strict";
 
-/*
-This constructor is always overridden with a blank constructor, and so shouldn't be used
-*/
-var WikiRuleBase = function() {
+/**
+ * @typedef {import('../base').Parser} Parser
+ */
+
+/**
+ * Base class for wiki rules.
+ * This constructor is always overridden with a blank constructor, and so shouldn't be used
+ * 
+ * @class
+ * @constructor
+ */
+function WikiRuleBase() {
+	/**
+	 * Inject by parser
+	 * @type {Record<"pragma"|"block"|"inline", boolean>}
+	 */
+	this.is = {};
+	/**
+	 * @type {RegExp}
+	 */
+	this.matchRegExp;
 };
 
-/*
-To be overridden by individual rules
-*/
+/**
+ * Initialize rule with given parser instance
+ * To be overridden by individual rules
+ * 
+ * @param {Parser} parser - Parser instance to initialize with
+ */
 WikiRuleBase.prototype.init = function(parser) {
 	this.parser = parser;
 };
 
-/*
-Default implementation of findNextMatch uses RegExp matching
-*/
+/**
+ * Default implementation of findNextMatch uses RegExp matching
+ * Find next match in source starting from given position using RegExp matching
+ * 
+ * @param {number} startPos - Position to start searching from
+ * @returns {number|undefined} Index of next match or undefined if no match is found
+ */
 WikiRuleBase.prototype.findNextMatch = function(startPos) {
 	this.matchRegExp.lastIndex = startPos;
 	this.match = this.matchRegExp.exec(this.parser.source);

core/modules/widgets/widget.js

@@ -12,22 +12,30 @@ Widget base class
 /*global $tw: false */
 "use strict";
 
-/*
-Create a widget object for a parse tree node
-	parseTreeNode: reference to the parse tree node to be rendered
-	options: see below
-Options include:
-	wiki: mandatory reference to wiki associated with this render tree
-	parentWidget: optional reference to a parent renderer node for the context chain
-	document: optional document object to use instead of global document
-*/
-var Widget = function(parseTreeNode,options) {
+/**
+ * Widget class for creating a widget object for a parse tree node.
+ * 
+ * @class
+ * @constructor
+ * @param {Object} parseTreeNode - Reference to the parse tree node to be rendered.
+ * @param {Object} options - Options for the widget.
+ * @param {Object} options.wiki - Mandatory reference to the wiki associated with this render tree.
+ * @param {Widget} [options.parentWidget] - Optional reference to a parent renderer node for the context chain.
+ * @param {Document} [options.document] - Optional document object to use instead of the global document.
+ */
+function Widget(parseTreeNode,options) {
 	this.initialise(parseTreeNode,options);
 };
 
-/*
-Initialise widget properties. These steps are pulled out of the constructor so that we can reuse them in subclasses
-*/
+/**
+ * Initialise widget properties. These steps are pulled out of the constructor so that we can reuse them in subclasses.
+ * 
+ * @param {Object} parseTreeNode - Reference to the parse tree node to be rendered.
+ * @param {Object} options - Options for the widget.
+ * @param {Object} options.wiki - Mandatory reference to the wiki associated with this render tree.
+ * @param {Widget} [options.parentWidget] - Optional reference to a parent renderer node for the context chain.
+ * @param {Document} [options.document] - Optional document object to use instead of the global document.
+ */
 Widget.prototype.initialise = function(parseTreeNode,options) {
 	// Bail if parseTreeNode is undefined, meaning  that the widget constructor was called without any arguments so that it can be subclassed
 	if(parseTreeNode === undefined) {
@@ -64,9 +72,12 @@ Widget.prototype.initialise = function(parseTreeNode,options) {
 	}
 };
 
-/*
-Render this widget into the DOM
-*/
+/**
+ * Render this widget into the DOM.
+ * 
+ * @param {Element} parent - The parent DOM node to render into.
+ * @param {Element} nextSibling - The next sibling DOM node to render before.
+ */
 Widget.prototype.render = function(parent,nextSibling) {
 	this.parentDomNode = parent;
 	this.execute();