Cleanup

wikimedia-gadgets · Nov 18, 2024 · 86f9015 · 86f9015
1 parent 656b00f
commit 86f9015
Show file tree

Hide file tree

Showing 2 changed files with 395 additions and 206 deletions.
diff --git a/scripts/api-types-generator-types.d.ts b/scripts/api-types-generator-types.d.ts
@@ -12,8 +12,9 @@ type CombinationOf<T extends string[], S extends string = " "> = T extends [infe
     : never;
 
 declare global {
-    type LineBlock = string[][];
-
+    /**
+     * Raw API module data.
+     */
     interface RawModule {
         name: string;
         classname: string[];
@@ -43,6 +44,9 @@ declare global {
             description: string;
         }
 
+        /**
+         * Raw API module parameter data.
+         */
         interface Parameter {
             index: number;
             module: RawModule;
@@ -108,7 +112,7 @@ declare global {
     }
 
     /**
-     * Pre-processed API module data.
+     * Processed API module data.
      */
     interface Module {
         /**
@@ -131,20 +135,27 @@ declare global {
          * Sorted list of properties.
          */
         parameters: Parameter[];
+        /**
+         * Full parameter prefix.
+         */
         prefix: string;
+        /**
+         * Module JSdoc.
+         */
         jsdoc?: Declaration.JSdoc;
     }
 
     /**
-     * If it is not an API root module, indicates a parameter and associated value providing this module as a sub-module.
+     * If it is not an API root module, indicates a parameter and associated value providing this
+     * module as a sub-module.
      */
     interface ParentPath {
         parameter: Parameter;
         value: string;
     }
 
     /**
-     * Pre-processed API parameter data.
+     * Processed API parameter data.
      */
     interface Parameter {
         /**
@@ -160,11 +171,11 @@ declare global {
          */
         module: Module;
         /**
-         * Whether the type name is a string template or litteral.
+         * Whether the type name is a string template or literal.
          */
         template?: boolean;
         /**
-         * Type.
+         * TS type.
          */
         type: Parameter.Type;
         /**
@@ -179,6 +190,9 @@ declare global {
     }
 
     namespace Parameter {
+        /**
+         * TS type of an API module parameter.
+         */
         type Type = Type.Single | Type.Multi;
 
         namespace Type {
@@ -188,11 +202,11 @@ declare global {
                  */
                 base?: string | Record<string, Module>;
                 /**
-                 * Possible litterals, that may not be part of the base type above.
+                 * Possible literals, that may not be part of the base type above.
                  */
                 lits?: Set<string>;
                 /**
-                 * Whether litterals can be specified as a list.
+                 * Whether literals can be specified as a list.
                  */
                 multi?: boolean;
             }
@@ -204,70 +218,171 @@ declare global {
             interface Multi extends Base {
                 multi: true;
                 /**
-                 * Possible litterals, that may not be part of the base type above, and can not be used in a list.
+                 * Possible literals, that may not be part of the base type above, and can not be
+                 * used in a list.
                  */
                 singleLits?: Set<string>;
             }
         }
     }
 
+    /**
+     * Stack of parent module parameters of a sub-module.
+     */
     type ParentStack =
         | {
               path: ParentPath;
               next: ParentStack;
           }
         | undefined;
 
+    /**
+     * Type declaration (either a type alias or interface).
+     */
     type Declaration = Declaration.Type | Declaration.Interface;
 
     namespace Declaration {
+        /**
+         * Something.
+         */
         interface Base {
+            /**
+             * JSdoc declaration.
+             */
             jsdoc?: JSdoc;
         }
 
+        /**
+         * Something that can be exported.
+         */
         interface Standalone extends Base {
+            /**
+             * Declaration modifier.
+             */
             modifier?: Modifier;
         }
 
+        /**
+         * Something that is a type-like declaration.
+         */
         interface Extendable extends Standalone {
+            /**
+             * Type name.
+             */
             name: string;
+            /**
+             * List of template type variables.
+             */
             template?: string[];
         }
 
+        /**
+         * Namespace declaration.
+         */
         interface Namespace extends Standalone {
+            /**
+             * Type declarations.
+             */
             declarations?: Declaration[];
+            /**
+             * Sub-namespaces.
+             */
             subnamespaces?: Record<string, Namespace>;
+            /**
+             * Set of deprecated type aliases.
+             */
             deprecated?: Record<string, DeprecationTarget[]>;
         }
 
+        /**
+         * Type alias declaration.
+         */
         interface Type extends Extendable {
+            /**
+             * Type expression.
+             */
             type: string;
         }
 
+        /**
+         * Interface declaration.
+         */
         interface Interface extends Extendable {
+            /**
+             * Set of parent types to inherit from.
+             */
             parents: string[];
+            /**
+             * Ordered list of properties.
+             */
             properties: Property[];
         }
 
+        /**
+         * Interface property declaration.
+         */
         interface Property extends Base {
+            /**
+             * Property name, as an interpolated TS string if `template`, otherwise as a string
+             * literal.
+             */
             name: string;
+            /**
+             * True if the property name is an interpolated TS string, false or undefined if it is
+             * a single literal.
+             */
             template?: boolean;
+            /**
+             * Property type.
+             */
             type: string;
+            /**
+             * True if the property is required, false or undefined if it is optional.
+             */
             required?: boolean;
         }
 
+        /**
+         * Declaration modifier.
+         */
         type Modifier = CombinationOf<["export", "declare"]>;
 
+        /**
+         * JSdoc declaration, associated to something.
+         */
         interface JSdoc {
+            /**
+             * JSdoc-compatible description.
+             */
             description?: string[];
+            /**
+             * True if the thing is private (and that can not be expressed with the TS type system),
+             * false or undefined otherwise.
+             */
             private?: boolean;
+            /**
+             * True or a JSdoc-compatible message if the thing is deprecated, false or undefined
+             * otherwise.
+             */
             deprecated?: string | boolean;
+            /**
+             * List of related links to include at the end of the JSdoc.
+             */
             seelinks?: string[];
         }
     }
 
+    /**
+     * Possible replacement of a deprecated type alias.
+     */
     interface DeprecationTarget {
+        /**
+         * Replacement type expression.
+         */
         type: string;
+        /**
+         * Link to put on the replacement type expression, used in JSdoc.
+         */
         link?: string;
     }
 }