Merge pull request #1135 from mathjax/refactor/more_jsdoc

Documentation cleanup

Author: zorkow

.eslintrc

@@ -20,15 +20,13 @@ export default tseslint.config({
   ignores: ["**/*.d.ts", "**/*.js"],
   "rules": {
     "@typescript-eslint/no-explicit-any": "off",
-    "@typescript-eslint/explicit-module-boundary-types": "off",
-    "@typescript-eslint/no-empty-function": "off",
-    "@typescript-eslint/no-unused-vars": ["error", { "varsIgnorePattern": "^_", "argsIgnorePattern": "^_", "caughtErrorsIgnorePattern": "^_" }],
+    "@typescript-eslint/no-unused-vars": ["error",
+                                          { "varsIgnorePattern": "^_", "argsIgnorePattern": "^_",
+                                            "caughtErrorsIgnorePattern": "^_" }
+                                         ],
     "@typescript-eslint/no-empty-object-type": ["error", {"allowInterfaces": "with-single-extends"}],
-    "no-inner-declarations": "off",
     "prefer-const": ["error", {"destructuring": "all"}],
-    "jsdoc/tag-lines": ["warn", "always", {"count": 0, "startLines": 1}],
-    "jsdoc/require-param-type": "off",
-    "jsdoc/require-returns-type": "off"
+    "jsdoc/tag-lines": ["warn", "always", {"count": 0, "startLines": 1}]
   }
 });
 

eslint.config.mjs

@@ -33,6 +33,7 @@ import { Explorer, AbstractExplorer } from './Explorer.js';
 import { ExplorerPool } from './ExplorerPool.js';
 import { MmlNode } from '../../core/MmlTree/MmlNode.js';
 import { honk, InPlace } from '../speech/SpeechUtil.js';
+import { GeneratorPool } from '../speech/GeneratorPool.js';
 import { Sre } from '../sre.js';
 
 /**
@@ -121,9 +122,9 @@ export class SpeechExplorer
   /**
    * Convenience getter for generator pool of the item.
    *
-   * @returns The item's generator pool.
+   * @returns {GeneratorPool} The item's generator pool.
    */
-  private get generators() {
+  private get generators(): GeneratorPool<HTMLElement, Text, Document> {
     return this.item?.generatorPool;
   }
 

ts/a11y/explorer/KeyExplorer.ts

@@ -67,9 +67,9 @@ function csPrefsVariables(menu: MJContextMenu, prefs: string[]) {
  *
  * @param {MJContextMenu} menu The current context menu.
  * @param {string} locale The current locale.
- * @returns The constructed selection box sub menu.
+ * @returns {object} The constructed selection box sub menu.
  */
-function csSelectionBox(menu: MJContextMenu, locale: string) {
+function csSelectionBox(menu: MJContextMenu, locale: string): object {
   const prefs = Sre.clearspeakPreferences.getLocalePreferences();
   const props = prefs[locale];
   if (!props) {
@@ -111,9 +111,9 @@ function csSelectionBox(menu: MJContextMenu, locale: string) {
  * Generates the menu items for the base preference menu.
  *
  * @param {string} previous The currently set preferences.
- * @returns The menu items.
+ * @returns {object[]} The menu items as a list of JSON objects.
  */
-function basePreferences(previous: string) {
+function basePreferences(previous: string): object[] {
   const items = [
     {
       type: 'radio',
@@ -140,9 +140,13 @@ function basePreferences(previous: string) {
  * @param {string} previous The currently set preferences.
  * @param {string} smart The semantic type of the smart preferences.
  * @param {string} locale The current locale.
- * @returns The menu of the smart choices.
+ * @returns {object[]} The menu of smart choices as a list of JSON objects.
  */
-function smartPreferences(previous: string, smart: string, locale: string) {
+function smartPreferences(
+  previous: string,
+  smart: string,
+  locale: string
+): object[] {
   const prefs = Sre.clearspeakPreferences.getLocalePreferences();
   const loc = prefs[locale];
   if (!loc) {

ts/a11y/speech/SpeechMenu.ts

@@ -42,12 +42,10 @@ export interface MinDocument<N, T> {
   body: N;
   title: string;
   doctype: { name: string };
-  /* tslint:disable:jsdoc-require */
   createElement(kind: string): N;
   createElementNS(ns: string, kind: string): N;
   createTextNode(text: string): T;
   querySelectorAll(selector: string): ArrayLike<N>;
-  /* tslint:enable */
 }
 
 /*****************************************************************/
@@ -81,7 +79,6 @@ export interface MinHTMLElement<N, T> {
   childNodes: (N | T)[] | NodeList;
   firstChild: N | T | Node;
   lastChild: N | T | Node;
-  /* tslint:disable:jsdoc-require */
   getElementsByTagName(name: string): N[] | HTMLCollectionOf<Element>;
   getElementsByTagNameNS(
     ns: string,
@@ -100,7 +97,6 @@ export interface MinHTMLElement<N, T> {
   hasAttribute(name: string): boolean;
   getBoundingClientRect(): object;
   getBBox?(): { x: number; y: number; width: number; height: number };
-  /* tslint:endable */
 }
 
 /*****************************************************************/

ts/adaptors/HTMLAdaptor.ts

@@ -376,7 +376,6 @@ function requestXML(
 ) {
   const request = getXMLHttpRequest();
   if (request) {
-    // tslint:disable-next-line:jsdoc-require
     request.onreadystatechange = function () {
       if (request.readyState === 4) {
         if (request.status === 200) {

ts/components/latest.ts

@@ -136,8 +136,8 @@ export const PathFilters: { [name: string]: PathFilterFunction } = {
   /**
    * Recursively replace path prefixes (e.g., [mathjax], [tex], etc.)
    *
-   * @param data The data object containing the filter functions
-   * @returns True
+   * @param {PathFilterFunction} data The data object containing the filter functions
+   * @returns {boolean} True
    */
   prefix: (data) => {
     let match;

ts/components/loader.ts

@@ -38,13 +38,11 @@ export type PackageMap = Map<string, Package>;
  * An error class that includes the package name
  */
 export class PackageError extends Error {
-  /* tslint:disable:jsdoc-require */
   public package: string;
   constructor(message: string, name: string) {
     super(message);
     this.package = name;
   }
-  /* tslint:enable */
 }
 
 /**
@@ -155,7 +153,8 @@ export class Package {
   }
 
   /**
-   * @param {string} name   A promise for when extra files and checkReady have been fulfilled
+   * @param {string} name The package configuration to be loaded
+   * @returns {Promise<void>} A promise for when extra files and checkReady have been fulfilled
    */
   public static loadPromise(name: string): Promise<void> {
     const config = (CONFIG[name] || {}) as PackageConfig;
@@ -249,8 +248,9 @@ export class Package {
   /**
    * @param {Promise<string>[]} promises  The array or promises that must be resolved before
    *                                        this package can load
+   * @returns {Promise<string>} The promise indicating when this file is loaded
    */
-  protected makePromise(promises: Promise<string>[]) {
+  protected makePromise(promises: Promise<string>[]): Promise<string> {
     //
     //  Make a promise and save its resolve/reject functions
     //

ts/components/package.ts

@@ -105,7 +105,6 @@ export interface MathJaxObject extends MJObject {
     document: MATHDOCUMENT;
     promise: Promise<void>;
     rerenderPromise: Promise<void>;
-    /* tslint:disable:jsdoc-require */
     registerConstructor(name: string, constructor: any): void;
     useHandler(name: string, force?: boolean): void;
     useAdaptor(name: string, force?: boolean): void;
@@ -125,7 +124,6 @@ export interface MathJaxObject extends MJObject {
     getOutputJax(): OUTPUTJAX;
     getAdaptor(): DOMADAPTOR;
     getHandler(): HANDLER;
-    /* tslint:enable */
   };
   [name: string]: any; // Needed for the methods created by the startup module
 }
@@ -320,8 +318,10 @@ export namespace Startup {
    * typesetting, if needed.
    *
    * Setting Mathjax.startup.pageReady in the configuration will override this.
+   *
+   * @returns {Promise<void>} Promise resolving when page is ready to process.
    */
-  export function defaultPageReady() {
+  export function defaultPageReady(): Promise<void> {
     return (
       CONFIG.loadAllFontFiles && (output as COMMONJAX).font
         ? (output as COMMONJAX).font.loadDynamicFiles()
@@ -338,9 +338,10 @@ export namespace Startup {
   /**
    * Perform the typesetting with handling of retries
    *
-   * @param elements The list of elements to typeset
+   * @param {any[]} elements The list of elements to typeset
+   * @returns {Promise<void>} The promise that resolves when elements are typeset
    */
-  export function typesetPromise(elements: any[]) {
+  export function typesetPromise(elements: any[]): Promise<void> {
     document.options.elements = elements;
     document.reset();
     return mathjax.handleRetriesFor(() => {

ts/components/startup.ts

@@ -228,14 +228,14 @@ export type ProtoItem<N, T> = {
 /**
  *  Produce a proto math item that can be turned into a MathItem
  *
- * @param open   The opening delimiter
- * @param math   The math expression itself
- * @param close  The closing delimiter
- * @param n      The index of the string in which this math is
- * @param start  The starting location of the math
- * @param end    The ending location of the math
- * @param display True means display mode, false is inline mode
- * @returns The proto math item
+ * @param {string} open   The opening delimiter
+ * @param {string} math   The math expression itself
+ * @param {string} close  The closing delimiter
+ * @param {number} n      The index of the string in which this math is
+ * @param {number} start  The starting location of the math
+ * @param {number} end    The ending location of the math
+ * @param {boolean} display True means display mode, false is inline mode
+ * @returns {ProtoItem<N, T>} The proto math item
  * @template N   The HTMLElement node class
  * @template T   The Text node class
  */