feat: add JSDoc example

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

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import('$:/core/modules/parsers/wikiparser/wikiparser.js')["text/vnd.tiddlywiki"]} WikiParser
+ * @typedef {import('$:/core/modules/widgets/widget.js').widget} Widget
+ */
+
 /*\
 title: $:/core/modules/wiki.js
 type: application/javascript
@@ -22,10 +27,6 @@ Adds the following properties to the wiki object:
 /*global $tw: false */
 "use strict";
 
-/**
- * @typedef {import('$:/core/modules/widgets/widget.js').widget} Widget
- */
-
 /**
  * @type {Widget}
  */
@@ -1048,19 +1049,26 @@ 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
-*/
+/**
+ * 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];
@@ -1150,14 +1158,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 || "";

package.json

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