feat: add JSDoc example

.gitignore

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

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

@@ -12,6 +12,25 @@ Wiki text rule for code blocks. For example:
 ```
 
 \*/
+
+/**
+ * Represents the `codeblock` rule.
+ * 
+ * @typedef {Object} CodeblockNode
+ * @property {string} type - The type of the widget, which is "codeblock".
+ * @property {Object} attributes - The attributes of the codeblock.
+ * @property {Object} attributes.code - The code attribute object.
+ * @property {string} attributes.code.type - The type of the code attribute, which is "string".
+ * @property {string} attributes.code.value - The actual code content within the code block.
+ * @property {number} attributes.code.start - The start position of the code in the source text.
+ * @property {number} attributes.code.end - The end position of the code in the source text.
+ * @property {Object} attributes.language - The language attribute object.
+ * @property {string} attributes.language.type - The type of the language attribute, which is "string".
+ * @property {string} attributes.language.value - The language specified after the triple backticks, if any.
+ * @property {number} attributes.language.start - The start position of the language string in the source text.
+ * @property {number} attributes.language.end - The end position of the language string in the source text.
+ */
+
 (function(){
 
 /*jslint node: true, browser: true */
@@ -21,12 +40,22 @@ Wiki text rule for code blocks. For example:
 exports.name = "codeblock";
 exports.types = {block: true};
 
+/**
+ * Initializes the codeblock rule with the given parser.
+ * 
+ * @param {Object} parser - The parser object that manages the state of the parsing process.
+ */
 exports.init = function(parser) {
 	this.parser = parser;
 	// Regexp to match and get language if defined
 	this.matchRegExp = /```([\w-]*)\r?\n/mg;
 };
 
+/**
+ * Parses the code block and returns an array of `codeblock` widgets.
+ * 
+ * @returns {CodeblockNode[]} 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/wikiparser.js

@@ -25,16 +25,20 @@ 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) {
+/**
+ * WikiParser class for parsing text of a specified MIME type.
+ * 
+ * @class
+ * @constructor
+ * @param {string} type - The content type of the text to be parsed.
+ * @param {string} text - The text to be parsed.
+ * @param {Object} options - Options for parsing.
+ * @param {boolean} [options.parseAsInline=false] - If true, the text will be parsed as an inline run.
+ * @param {Object} options.wiki - Reference to the wiki to use.
+ * @param {string} [options._canonical_uri] - Optional URI of the content if the text is missing or empty.
+ * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration.
+ */
+function WikiParser(type,text,options) {
 	this.wiki = options.wiki;
 	var self = this;
 	// Check for an externally linked tiddler
@@ -99,8 +103,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/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();

core/modules/wiki.js

@@ -16,13 +16,8 @@ Adds the following properties to the wiki object:
 * `globalCache` is a hashmap by cache name of cache objects that are cleared whenever any tiddler change occurs
 
 \*/
-(function(){
 
-/*jslint node: true, browser: true */
-/*global $tw: false */
-"use strict";
-
-var widget = require("$:/core/modules/widgets/widget.js");
+var Widget = require("$:/core/modules/widgets/widget.js").widget;
 
 var USER_NAME_TITLE = "$:/status/UserName",
 	TIMESTAMP_DISABLE_TITLE = "$:/config/TimestampDisable";
@@ -1041,19 +1036,30 @@ exports.initParsers = function(moduleType) {
 	}
 };
 
-/*
-Parse a block of text of a specified MIME type
-	type: content type of text to be parsed
-	text: text
-	options: see below
-Options include:
-	parseAsInline: if true, the text of the tiddler will be parsed as an inline run
-	_canonical_uri: optional string of the canonical URI of this content
-*/
+/**
+ * @typedef {import('$:/core/modules/parsers/wikiparser/wikiparser.js')["text/vnd.tiddlywiki"]} WikiParser
+ */
+
+/**
+ * Parse a block of text of a specified MIME type.
+ * 
+ * @param {string} type - The content type of the text to be parsed.
+ * @param {string} text - The text to be parsed.
+ * @param {Object} [options] - Options for parsing.
+ * @param {boolean} [options.parseAsInline=false] - If true, the text will be parsed as an inline run.
+ * @param {string} [options._canonical_uri] - Optional string of the canonical URI of this content.
+ * @param {string} [options.defaultType="text/vnd.tiddlywiki"] - The default type to use if no parser is found for the specified type.
+ * @param {boolean} [options.configTrimWhiteSpace=false] - If true, trims white space according to configuration.
+ * 
+ * @returns {WikiParser|null} The parser instance or null if no parser is found.
+ */
 exports.parseText = function(type,text,options) {
 	text = text || "";
 	options = options || {};
-	// Select a parser
+	/**
+	 * @type WikiParser
+	 * Select a parser
+	 */
 	var Parser = $tw.Wiki.parsers[type];
 	if(!Parser && $tw.utils.getFileExtensionInfo(type)) {
 		Parser = $tw.Wiki.parsers[$tw.utils.getFileExtensionInfo(type).type];
@@ -1143,14 +1149,16 @@ exports.getTextReferenceParserInfo = function(title,field,index,options) {
 	return parserInfo;
 }
 
-/*
-Parse a block of text of a specified MIME type
-	text: text on which to perform substitutions
-	widget
-	options: see below
-Options include:
-	substitutions: an optional array of substitutions
-*/
+/**
+ * Parse a block of text of a specified MIME type and perform substitutions.
+ * 
+ * @param {string} text - The text on which to perform substitutions.
+ * @param {Widget} widget - The widget context used for variable substitution.
+ * @param {Object} [options] - Options for substitutions.
+ * @param {Array<{name: string, value: string}>} [options.substitutions] - An optional array of substitutions.
+ * 
+ * @returns {string} The text with substitutions applied.
+ */
 exports.getSubstitutedText = function(text,widget,options) {
 	options = options || {};
 	text = text || "";
@@ -1171,15 +1179,17 @@ exports.getSubstitutedText = function(text,widget,options) {
 	});
 };
 
-/*
-Make a widget tree for a parse tree
-parser: parser object
-options: see below
-Options include:
-document: optional document to use
-variables: hashmap of variables to set
-parentWidget: optional parent widget for the root node
-*/
+/**
+ * Create a widget tree for a parse tree.
+ * 
+ * @param {Object} parser - The parser object containing the parse tree.
+ * @param {Object} [options] - Options for creating the widget tree.
+ * @param {Document} [options.document] - Optional document to use.
+ * @param {Object} [options.variables] - Hashmap of variables to set.
+ * @param {Widget} [options.parentWidget] - Optional parent widget for the root node.
+ * 
+ * @returns {Widget} The root widget of the created widget tree.
+ */
 exports.makeWidget = function(parser,options) {
 	options = options || {};
 	var widgetNode = {
@@ -1204,7 +1214,7 @@ exports.makeWidget = function(parser,options) {
 	// Add in the supplied parse tree nodes
 	currWidgetNode.children = parser ? parser.tree : [];
 	// Create the widget
-	return new widget.widget(widgetNode,{
+	return new Widget(widgetNode,{
 		wiki: this,
 		document: options.document || $tw.fakeDocument,
 		parentWidget: options.parentWidget
@@ -1487,9 +1497,13 @@ exports.search = function(text,options) {
 	return results;
 };
 
-/*
-Trigger a load for a tiddler if it is skinny. Returns the text, or undefined if the tiddler is missing, null if the tiddler is being lazily loaded.
-*/
+/**
+ * Trigger a load for a tiddler if it is skinny. Returns the text, or undefined if the tiddler is missing, null if the tiddler is being lazily loaded.
+ *
+ * @param {string} title - The title of the tiddler.
+ * @param {string} [defaultText] - The default text to return if the tiddler is missing.
+ * @returns {string | null | undefined} - The text of the tiddler, undefined if the tiddler is missing, or null if the tiddler is being lazily loaded.
+ */
 exports.getTiddlerText = function(title,defaultText) {
 	var tiddler = this.getTiddler(title);
 	// Return undefined if the tiddler isn't found
@@ -1781,5 +1795,3 @@ exports.slugify = function(title,options) {
 	}
 	return slug;
 };
-
-})();

package.json

@@ -13,6 +13,7 @@
   "bin": {
     "tiddlywiki": "./tiddlywiki.js"
   },
+  "types": "./types/tw.d.ts",
   "main": "./boot/boot.js",
   "repository": {
     "type": "git",

tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "paths": {
+      // Allow `import('$:/core/modules/...')` instead of `import('../../core/modules/...')`. Only works inside this project.
+      "$:/core/*": ["./core/*"]
+    },
+    "noImplicitAny": false,
+    "strict": false,
+
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "checkJs": true,
+    "declaration": true,
+    "declarationDir": "types/generated",
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "Node16",
+    "outDir": "types/generated",
+    "rootDir": ".",
+    "skipLibCheck": true,
+    "target": "ESNext"
+  },
+  "include": ["./core/**/*.js", "./core/**/*.d.ts", "types/tw.d.ts"],
+  "exclude": ["types/generated"]
+}

types/tw.d.ts

@@ -0,0 +1,7 @@
+import * as Wiki from '../core/modules/wiki';
+
+declare global {
+  var $tw: {
+    wiki: typeof Wiki;
+  };
+}