improve typings and add module documentation for extensions (#5827)

Author: mkslanc

ace-internal.d.ts

@@ -88,9 +88,13 @@ export namespace Ace {
     }
 
     interface HardWrapOptions {
+        /** First row of the range to process */
         startRow: number;
+        /** Last row of the range to process */
         endRow: number;
+        /** Whether to merge short adjacent lines that fit within the limit */
         allowMerge?: boolean;
+        /** Maximum column width for line wrapping (defaults to editor's print margin) */
         column?: number;
     }
 
@@ -971,24 +975,34 @@ export namespace Ace {
     type CompleterCallback = (error: any, completions: Completion[]) => void;
 
     interface Completer {
+        /** Regular expressions defining valid identifier characters for completion triggers */
         identifierRegexps?: Array<RegExp>,
 
+        /** Main completion method that provides suggestions for the given context */
         getCompletions(editor: Editor,
                        session: EditSession,
                        position: Point,
                        prefix: string,
                        callback: CompleterCallback): void;
 
+        /** Returns documentation tooltip for a completion item */
         getDocTooltip?(item: Completion): void | string | Completion;
 
+        /** Called when a completion item becomes visible */
         onSeen?: (editor: Ace.Editor, completion: Completion) => void;
+        /** Called when a completion item is inserted */
         onInsert?: (editor: Ace.Editor, completion: Completion) => void;
 
+        /** Cleanup method called when completion is cancelled */
         cancel?(): void;
 
+        /** Unique identifier for this completer */
         id?: string;
+        /** Characters that trigger autocompletion when typed */
         triggerCharacters?: string[];
+        /** Whether to hide inline preview text */
         hideInlinePreview?: boolean;
+        /** Custom insertion handler for completion items */
         insertMatch?: (editor: Editor, data: Completion) => void;
     }
 
@@ -1252,10 +1266,15 @@ export namespace Ace {
     }>>
 
     export interface StaticHighlightOptions {
+        /** Syntax mode (e.g., 'ace/mode/javascript'). Auto-detected from CSS class if not provided */
         mode?: string | SyntaxMode,
+        /** Color theme (e.g., 'ace/theme/textmate'). Defaults to 'ace/theme/textmate' */
         theme?: string | Theme,
+        /** Whether to trim whitespace from code content */
         trim?: boolean,
+        /** Starting line number for display */
         firstLineNumber?: number,
+        /** Whether to show line numbers gutter */
         showGutter?: boolean
     }
 
@@ -1294,6 +1313,28 @@ export namespace Ace {
         setLabel?: boolean;
         inline?: boolean;
     }
+
+    export interface TextAreaOptions {
+        /** Programming language mode for syntax highlighting (e.g., "javascript", "html", "css") */
+        mode?: string;
+        /** Visual theme for the editor appearance (e.g., "textmate", "monokai", "eclipse") */
+        theme?: string;
+        /** Line wrapping behavior - "off", "free", or specific column number like "40", "80" */
+        wrap?: string | number;
+        /** Font size in CSS units (e.g., "12px", "14px", "16px") */
+        fontSize?: string;
+        /** Whether to display the line number gutter on the left side */
+        showGutter?: boolean | string;
+        /** Keyboard handler/bindings to use - "ace", "vim", or "emacs" */
+        keybindings?: string;
+        /** Whether to show the print margin indicator line */
+        showPrintMargin?: boolean | string;
+        /** Whether to use soft tabs (spaces) instead of hard tabs */
+        useSoftTabs?: boolean | string;
+        /** Whether to show invisible characters like spaces and tabs */
+        showInvisibles?: boolean | string;
+    }
+
 }
 
 

ace.d.ts

@@ -86,9 +86,13 @@ declare module "ace-code" {
             gutterOffset: number;
         }
         interface HardWrapOptions {
+            /** First row of the range to process */
             startRow: number;
+            /** Last row of the range to process */
             endRow: number;
+            /** Whether to merge short adjacent lines that fit within the limit */
             allowMerge?: boolean;
+            /** Maximum column width for line wrapping (defaults to editor's print margin) */
             column?: number;
         }
         interface CommandBarOptions {
@@ -778,15 +782,25 @@ declare module "ace-code" {
         };
         type CompleterCallback = (error: any, completions: Completion[]) => void;
         interface Completer {
+            /** Regular expressions defining valid identifier characters for completion triggers */
             identifierRegexps?: Array<RegExp>;
+            /** Main completion method that provides suggestions for the given context */
             getCompletions(editor: Editor, session: EditSession, position: Point, prefix: string, callback: CompleterCallback): void;
+            /** Returns documentation tooltip for a completion item */
             getDocTooltip?(item: Completion): void | string | Completion;
+            /** Called when a completion item becomes visible */
             onSeen?: (editor: Ace.Editor, completion: Completion) => void;
+            /** Called when a completion item is inserted */
             onInsert?: (editor: Ace.Editor, completion: Completion) => void;
+            /** Cleanup method called when completion is cancelled */
             cancel?(): void;
+            /** Unique identifier for this completer */
             id?: string;
+            /** Characters that trigger autocompletion when typed */
             triggerCharacters?: string[];
+            /** Whether to hide inline preview text */
             hideInlinePreview?: boolean;
+            /** Custom insertion handler for completion items */
             insertMatch?: (editor: Editor, data: Completion) => void;
         }
         interface CompletionOptions {
@@ -985,10 +999,15 @@ declare module "ace-code" {
             value: string;
         }>>;
         export interface StaticHighlightOptions {
+            /** Syntax mode (e.g., 'ace/mode/javascript'). Auto-detected from CSS class if not provided */
             mode?: string | SyntaxMode;
+            /** Color theme (e.g., 'ace/theme/textmate'). Defaults to 'ace/theme/textmate' */
             theme?: string | Theme;
+            /** Whether to trim whitespace from code content */
             trim?: boolean;
+            /** Starting line number for display */
             firstLineNumber?: number;
+            /** Whether to show line numbers gutter */
             showGutter?: boolean;
         }
         export interface Operation {
@@ -1031,6 +1050,26 @@ declare module "ace-code" {
             setLabel?: boolean;
             inline?: boolean;
         }
+        export interface TextAreaOptions {
+            /** Programming language mode for syntax highlighting (e.g., "javascript", "html", "css") */
+            mode?: string;
+            /** Visual theme for the editor appearance (e.g., "textmate", "monokai", "eclipse") */
+            theme?: string;
+            /** Line wrapping behavior - "off", "free", or specific column number like "40", "80" */
+            wrap?: string | number;
+            /** Font size in CSS units (e.g., "12px", "14px", "16px") */
+            fontSize?: string;
+            /** Whether to display the line number gutter on the left side */
+            showGutter?: boolean | string;
+            /** Keyboard handler/bindings to use - "ace", "vim", or "emacs" */
+            keybindings?: string;
+            /** Whether to show the print margin indicator line */
+            showPrintMargin?: boolean | string;
+            /** Whether to use soft tabs (spaces) instead of hard tabs */
+            useSoftTabs?: boolean | string;
+            /** Whether to show invisible characters like spaces and tabs */
+            showInvisibles?: boolean | string;
+        }
     }
     export const config: typeof import("ace-code/src/config");
     export function edit(el?: string | (HTMLElement & {

src/ext/beautify.js

@@ -1,30 +1,61 @@
-// [WIP]
+/**
+ * ## Code beautification and formatting extension.
+ *
+ * **This extension is considered outdated.** For better formatting support with modern language servers
+ * and advanced formatting capabilities, consider using [ace-linters](https://github.com/mkslanc/ace-linters)
+ * which provides comprehensive language support including formatting, linting, and IntelliSense features.
+ *
+ * This legacy extension provides basic formatting for HTML, CSS, JavaScript, and PHP code with support for
+ * proper indentation, whitespace management, line breaks, and bracket alignment. It handles various language
+ * constructs including HTML tags, CSS selectors, JavaScript operators, control structures, and maintains
+ * consistent code style throughout the document.
+ *
+ * @module
+ */
+
 
 "use strict";
+
 var TokenIterator = require("../token_iterator").TokenIterator;
 
 function is(token, type) {
     return token.type.lastIndexOf(type + ".xml") > -1;
 }
 
-// do not indent after singleton tags or <html>
+/**
+ * List of HTML singleton (self-closing) tags that do not require additional indentation.
+ * These tags are typically void elements that cannot have child content and are closed within themselves.
+ *
+ * @type {string[]}
+ * @exports
+ */
 exports.singletonTags = ["area", "base", "br", "col", "command", "embed", "hr", "html", "img", "input", "keygen", "link", "meta", "param", "source", "track", "wbr"];
 
-// insert a line break after block level tags
+/**
+ * List of HTML block-level tags that typically require line breaks after their opening and closing tags.
+ * These tags represent structural elements that usually contain other content and are rendered as block-level elements.
+ *
+ * @type {string[]}
+ */
 exports.blockTags = ["article", "aside", "blockquote", "body", "div", "dl", "fieldset", "footer", "form", "head", "header", "html", "nav", "ol", "p", "script", "section", "style", "table", "tbody", "tfoot", "thead", "ul"];
 
 /**
- * 
+ * Configuration options for code formatting behavior.
+ * Controls various formatting rules such as line break placement and spacing preferences.
+ *
  * @type {{lineBreaksAfterCommasInCurlyBlock?: boolean}}
  */
 exports.formatOptions = {
     lineBreaksAfterCommasInCurlyBlock: true
 };
 
 /**
- * 
- * @param {import("../edit_session").EditSession} session
+ * Formats and beautifies code in the editor session with intelligent indentation, whitespace management, and bracket alignment.
+ * Supports HTML, CSS, JavaScript, and PHP with configurable formatting options and language-specific rules.
+ *
+ * @param {import("../edit_session").EditSession} session - The editor session containing the code to format
  */
+
 exports.beautify = function(session) {
     var iterator = new TokenIterator(session, 0, 0);
     var token = iterator.getCurrentToken();
@@ -398,6 +429,12 @@ exports.beautify = function(session) {
     session.doc.setValue(code);
 };
 
+/**
+ * Array of command definitions for the beautify extension.
+ * Contains the main beautify command with keyboard shortcut and execution handler.
+ *
+ * @type {import("../../ace-internal").Ace.Command[]}
+ */
 exports.commands = [{
     name: "beautify",
     description: "Format selection (Beautify)",

src/ext/code_lens.js

@@ -1,3 +1,11 @@
+/**
+ * ## Code Lens extension.
+ *
+ * Displaying contextual information and clickable commands above code lines. Supports registering custom providers,
+ * rendering lens widgets with proper positioning and styling, and handling user interactions with lens commands.
+ * @module
+ */
+
 "use strict";
 /**
  * @typedef {import("../edit_session").EditSession} EditSession

src/ext/command_bar.js

@@ -1,3 +1,14 @@
+/**
+ * ## Command Bar extension.
+ *
+ * Provides an interactive command bar tooltip that displays above the editor's active line. The extension enables
+ * clickable commands with keyboard shortcuts, icons, and various button types including standard buttons, checkboxes,
+ * and text elements. Supports overflow handling with a secondary tooltip for additional commands when space is limited.
+ * The tooltip can be configured to always show or display only on mouse hover over the active line.
+ *
+ * @module
+ */
+
 /**
  * @typedef {import("../editor").Editor} Editor
  * @typedef {import("../../ace-internal").Ace.TooltipCommand} TooltipCommand

src/ext/elastic_tabstops_lite.js

@@ -1,3 +1,15 @@
+/**
+ * ## Elastic Tabstops Lite extension.
+ *
+ * Automatically adjusts tab spacing to align content in tabular format by calculating optimal column widths
+ * and maintaining consistent vertical alignment across multiple lines. Tracks content changes and dynamically
+ * reprocesses affected rows to ensure proper formatting without manual intervention.
+ *
+ * **Enable:** `editor.setOption("useElasticTabstops", true)`
+ *  or configure it during editor initialization in the options object.
+ * @module
+ */
+
 "use strict";
 class ElasticTabstopsLite {
     /**

src/ext/emmet.js

@@ -1,3 +1,13 @@
+/**
+ * ## Emmet extension
+ *
+ * Providing HTML/CSS abbreviation expansion, code navigation, and text editing utilities with configurable options and
+ * keyboard shortcuts for rapid web development workflow.
+ *
+ * **Enable:** `editor.setOption("enableEmmet", true)`
+ * or configure it during editor initialization in the options object.
+ * @module
+ */
 "use strict";
 var HashHandler = require("../keyboard/hash_handler").HashHandler;
 var Editor = require("../editor").Editor;
@@ -322,9 +332,12 @@ var keymap = {
 
 var editorProxy = new AceEmmetEditor();
 exports.commands = new HashHandler();
+
 /**
- * @param {Editor} editor
- * @return {ReturnType<typeof setTimeout> | boolean}
+ * Runs an Emmet command on the given editor.
+ *
+ * @param {Editor} editor - The Ace editor instance to run the Emmet command on
+ * @return {ReturnType<typeof setTimeout> | boolean} The result of the Emmet command execution
  */
 exports.runEmmetCommand = function runEmmetCommand(editor) {
     if (this.action == "expand_abbreviation_with_tab") {
@@ -372,8 +385,10 @@ for (var command in keymap) {
 }
 
 /**
- * @param {Editor} editor
- * @param {boolean} [enabled]
+ * Updates the keyboard handler for Emmet commands in the editor.
+ *
+ * @param {Editor} editor - The Ace editor instance
+ * @param {boolean} [enabled] - Whether Emmet commands should be enabled
  */
 exports.updateCommands = function(editor, enabled) {
     if (enabled) {
@@ -383,6 +398,12 @@ exports.updateCommands = function(editor, enabled) {
     }
 };
 
+/**
+ * Determines if a given editor mode is supported by Emmet.
+ *
+ * @param {Object|string} mode - The editor mode to check for Emmet support
+ * @returns {boolean} Whether the mode is supported by Emmet
+ */
 exports.isSupportedMode = function(mode) {
     if (!mode) return false;
     if (mode.emmetConfig) return true;
@@ -391,9 +412,11 @@ exports.isSupportedMode = function(mode) {
 };
 
 /**
- * @param {Editor} editor
- * @param {string} command
- * @return {boolean}
+ * Checks if an Emmet command is available for the current editor context.
+ *
+ * @param {Editor} editor - The current Ace editor instance
+ * @param {string} command - The Emmet command to check availability for
+ * @return {boolean} Whether the command is available in the current editor mode
  */
 exports.isAvailable = function(editor, command) {
     if (/(evaluate_math_expression|expand_abbreviation)$/.test(command))
@@ -423,6 +446,12 @@ var onChangeMode = function(e, target) {
     exports.updateCommands(editor, enabled);
 };
 
+/**
+ * Loads the Emmet core module dynamically.
+ *
+ * @param {Function} [cb] - Optional callback function to be executed after module loading
+ * @return {boolean} Whether the Emmet core module loading was initiated successfully
+ */
 exports.load = function(cb) {
     if (typeof emmetPath !== "string") {
         config.warn("script for emmet-core is not loaded");
@@ -446,6 +475,13 @@ config.defineOptions(Editor.prototype, "editor", {
     }
 });
 
+/**
+ * Sets the Emmet core module or path.
+ *
+ * @param {string|Object} e - Either the path to the Emmet core script or the Emmet core module itself
+ * If a string is provided, it sets the path to load the Emmet core script.
+ * If an object is provided, it directly sets the Emmet core module.
+ */
 exports.setCore = function(e) {
     if (typeof e == "string")
        emmetPath = e;