simplify docstrings

Author: LucasLefevre

src/components/composer/composer/prettifier_content.ts

@@ -3,91 +3,81 @@ import {
   leftOperandNeedsParenthesis,
   rightOperandNeedsParenthesis,
 } from "../../../formulas/parser";
+import { memoize } from "../../../helpers";
 
 /**
- * This file implements a prettifier for Abstract Syntax Trees (ASTs) used in
- * spreadsheet formulas. The prettifier converts an AST into a human-readable
- * string representation, ensuring proper formatting with indentation, line
- * breaks, and grouping based on available width constraints.
+ * Pretty-prints formula ASTs into readable formulas.
  *
- * The core functionality revolves around the `Doc` structure, which represents
- * formatting elements such as concatenation, nesting, and line insertion. The
- * prettifier dynamically selects the best formatting option based on the
- * available width, producing a compact or expanded representation as needed.
+ * Implements a Wadler-inspired pretty printer:
+ * it converts an AST into a `Doc` structure,
+ * and then chooses between compact (flat) or expanded (with
+ * line breaks and indentation) layouts depending on space.
  *
- * The implementation is inspired by the blog article:
- * https://lik.ai/blog/how-a-pretty-printer-works/
- *
- * Key components:
- * - `Doc` structure: Represents formatting options for ASTs.
- * - `print`: Converts a `Doc` into a string representation that fits within a
- *   specified width.
- * - `astToDoc`: Transforms an AST into a `Doc` structure for formatting.
- * - Dynamic line breaking and indentation: Ensures the output is readable and
- *   fits within constraints.
+ * References:
+ * - https://lik.ai/blog/how-a-pretty-printer-works/
+ * - Wadler, "A prettier printer": https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf
  */
-
-export function prettify(ast: AST) {
+export function prettify(ast: AST): string {
   return "=" + print(astToDoc(ast), 59); // 59 but 60 with the `=` at the beginning
 }
 
 // ---------------------------------------
 // Doc structure
 // ---------------------------------------
 
-// The `Doc` structure represents the possible ways to format an Abstract Syntax
-// Tree (AST) into a human-readable string.
-// It includes formatting elements such as line breaks, indentation, and token
-// grouping.
-//
-// Once created, this structure is used to determine the best formatting path
-// based on the available width, allowing dynamic selection of the most suitable
-// string representation for the given constraints.
-
+/**
+ * A `Doc` represents alternative layouts (tree of layouts) for pretty-printing.
+ * The printer chooses the layout that fits best within the available width.
+ */
 type Doc = string | ChooseBetween | Concat | Nest | InsertLine;
 
 type ChooseBetween = { type: "chooseBetween"; doc1: Doc; doc2: Doc };
 type Concat = { type: "concat"; docs: Doc[] };
 type Nest = { type: "nest"; indentLevel: number; doc: Doc };
 type InsertLine = { type: "insertLine" };
 
-/** Represents a line break that can be inserted when formatting the document.
- * Used in groups to dynamically decide where to break lines based on available space.
+/**
+ * A possible line break.
+ * Printed as either space or newline.
  */
 function line(): InsertLine {
   return { type: "insertLine" };
 }
 
-/** Represents a nested structure with a specific indentation level.
- * Useful for formatting hierarchical or indented content.
+/**
+ * Increase indentation for a nested block.
  */
 function nest(indentLevel: number, doc: Doc): Nest {
   return { type: "nest", indentLevel, doc };
 }
 
-/** Concatenates multiple `Doc` elements into a single `Doc`.
- * This is the primary way to combine strings and other formatting elements.
+/**
+ * Combines multiple docs into a single doc, concatenating them side by side
+ * without any line breaks or indentation.
  */
 function concat(docs: Doc[]): Concat {
   return { type: "concat", docs };
 }
 
-/** Groups a `Doc` to allow dynamic selection between a flattened version
- * (single-line representation) and the original structure based on available space.
+/**
+ * Marks a document as a unit to be printed "flat" (all on one line)
+ * if it fits within the width, otherwise with line breaks.
  */
 function group(doc: Doc): ChooseBetween {
   return chooseBetween(flatten(doc), doc);
 }
 
-/** Creates a choice between two `Doc` structures, typically used in `group`.
- * The choice depends on whether the available space can accommodate the flattened version.
+/**
+ * Creates a choice between two alternative layouts.
+ * The formatter tries `doc1`; if it does not fit within
+ * the line width, it falls back to `doc2`.
  */
 function chooseBetween(doc1: Doc, doc2: Doc): ChooseBetween {
   return { type: "chooseBetween", doc1, doc2 };
 }
 
-/** Flattens a `Doc` structure into a single-line representation.
- * Used exclusively for `group` to create the flattened alternative.
+/**
+ * Flattens a doc into its single-line form.
  */
 function flatten(doc: Doc): Doc {
   if (typeof doc === "string") {
@@ -120,34 +110,27 @@ function flatten(doc: Doc): Doc {
 
 /**
  * A linked list for string segments.
+ * Used to avoid large string concatenations during layout selection.
  */
 interface LinkedString {
   subString: string;
   next: LinkedString | null;
 }
 
-/**
- * Memoized helper to build indentation strings.
- */
-const memoizedIndentation: Record<number, string> = {};
-function getIndentation(indentLevel: number): string {
-  if (!(indentLevel in memoizedIndentation)) {
-    memoizedIndentation[indentLevel] = "\n" + "\t".repeat(indentLevel);
-  }
-  return memoizedIndentation[indentLevel];
-}
+const getIndentationString = memoize(function getIndentationString(indentLevel: number): string {
+  return "\n" + "\t".repeat(indentLevel);
+});
 
 /**
- * Converts a `Doc` structure into a string representation that fits within
+ * Converts a `Doc` into a string representation that fits within
  * the specified width.
  */
 function print(doc: Doc, width: number): string {
-  return stringify(selectBestLinkedString(width, doc));
+  return stringify(selectBestLayout(width, doc));
 }
 
 /**
- * Recursively converts a `LinkedString` object into a human-readable string.
- * This is the final step of the prettifier process.
+ * Join all segments of a LinkedString into the final string.
  */
 function stringify(linkedString: LinkedString | null): string {
   let result = "";
@@ -159,16 +142,15 @@ function stringify(linkedString: LinkedString | null): string {
 }
 
 /**
- * Selects the best `LinkedString` representation of a `Doc` that fits within
- * the given width.
+ * Layout selection for a `Doc` that fits within the given width.
  */
-function selectBestLinkedString(width: number, doc: Doc): LinkedString | null {
+function selectBestLayout(width: number, doc: Doc): LinkedString | null {
   const head: RestToFitNode = {
     indentLevel: 0,
     doc,
     next: null,
   };
-  return _selectBestLinkedString(width, 0, head);
+  return _selectBestLayout(width, 0, head);
 }
 
 /**
@@ -180,7 +162,7 @@ interface RestToFitNode {
   next: RestToFitNode | null;
 }
 
-function _selectBestLinkedString(
+function _selectBestLayout(
   width: number,
   currentIndentLevel: number,
   head: RestToFitNode | null
@@ -194,44 +176,44 @@ function _selectBestLinkedString(
   if (typeof doc === "string") {
     return {
       subString: doc,
-      next: _selectBestLinkedString(width, currentIndentLevel + doc.length, next),
+      next: _selectBestLayout(width, currentIndentLevel + doc.length, next),
     };
   }
   if (doc.type === "concat") {
     let newHead = next;
     for (let i = doc.docs.length - 1; i >= 0; i--) {
       newHead = { indentLevel, doc: doc.docs[i], next: newHead };
     }
-    return _selectBestLinkedString(width, currentIndentLevel, newHead);
+    return _selectBestLayout(width, currentIndentLevel, newHead);
   }
   if (doc.type === "nest") {
-    return _selectBestLinkedString(width, currentIndentLevel, {
+    return _selectBestLayout(width, currentIndentLevel, {
       indentLevel: indentLevel + doc.indentLevel,
       doc: doc.doc,
       next,
     });
   }
   if (doc.type === "insertLine") {
     return {
-      subString: getIndentation(indentLevel),
-      next: _selectBestLinkedString(width, indentLevel, next),
+      subString: getIndentationString(indentLevel),
+      next: _selectBestLayout(width, indentLevel, next),
     };
   }
   if (doc.type === "chooseBetween") {
     const head1 = { indentLevel, doc: doc.doc1, next };
-    const possibleLinkedString = _selectBestLinkedString(width, currentIndentLevel, head1);
+    const possibleLinkedString = _selectBestLayout(width, currentIndentLevel, head1);
     if (fits(width - currentIndentLevel, possibleLinkedString)) {
       return possibleLinkedString;
     }
 
     const head2 = { indentLevel, doc: doc.doc2, next };
-    return _selectBestLinkedString(width, currentIndentLevel, head2);
+    return _selectBestLayout(width, currentIndentLevel, head2);
   }
   return null;
 }
 
 /**
- * Checks whether a given `LinkedString` fits within the specified width.
+ * Check if a layout fits on a single line within width.
  */
 function fits(width: number, linkedString: LinkedString | null): boolean {
   while (linkedString) {
@@ -245,13 +227,6 @@ function fits(width: number, linkedString: LinkedString | null): boolean {
   return true;
 }
 
-// ---------------------------------------
-// AST part
-// ---------------------------------------
-
-/**
- * Converts an AST into a `Doc` structure for formatting.
- */
 function astToDoc(ast: AST): Doc {
   switch (ast.type) {
     case "NUMBER":
@@ -268,7 +243,7 @@ function astToDoc(ast: AST): Doc {
 
     case "FUNCALL":
       const docs = ast.args.map(astToDoc);
-      return splitParenthesesContent(
+      return wrapInParentheses(
         concat(docs.map((doc, i) => (i < 1 ? doc : concat([", ", line(), doc])))),
         ast.value
       );
@@ -278,7 +253,7 @@ function astToDoc(ast: AST): Doc {
       const needParenthesis = ast.postfix
         ? leftOperandNeedsParenthesis(ast)
         : rightOperandNeedsParenthesis(ast);
-      const finalOperandDoc = needParenthesis ? splitParenthesesContent(operandDoc) : operandDoc;
+      const finalOperandDoc = needParenthesis ? wrapInParentheses(operandDoc) : operandDoc;
 
       return ast.postfix
         ? concat([finalOperandDoc, ast.value])
@@ -287,11 +262,11 @@ function astToDoc(ast: AST): Doc {
     case "BIN_OPERATION": {
       const leftDoc = astToDoc(ast.left);
       const needParenthesisLeftDoc = leftOperandNeedsParenthesis(ast);
-      const finalLeftDoc = needParenthesisLeftDoc ? splitParenthesesContent(leftDoc) : leftDoc;
+      const finalLeftDoc = needParenthesisLeftDoc ? wrapInParentheses(leftDoc) : leftDoc;
 
       const rightDoc = astToDoc(ast.right);
       const needParenthesisRightDoc = rightOperandNeedsParenthesis(ast);
-      const finalRightDoc = needParenthesisRightDoc ? splitParenthesesContent(rightDoc) : rightDoc;
+      const finalRightDoc = needParenthesisRightDoc ? wrapInParentheses(rightDoc) : rightDoc;
 
       const operator = `${ast.value}`;
       return group(concat([finalLeftDoc, operator, nest(1, concat([line(), finalRightDoc]))]));
@@ -306,9 +281,9 @@ function astToDoc(ast: AST): Doc {
 }
 
 /**
- * Wraps a `Doc` in parentheses and optionally prepends a function name.
+ * Wraps a `Doc` in parentheses (with optional function name).
  */
-function splitParenthesesContent(doc: Doc, functionName: undefined | string = undefined): Doc {
+function wrapInParentheses(doc: Doc, functionName: undefined | string = undefined): Doc {
   const docToConcat = ["(", nest(1, concat([line(), doc])), line(), ")"];
   if (functionName) {
     docToConcat.unshift(functionName);