Make LiquidDoc @param description dash seperator a configurable prettier option and simplify types

Now that this is a configurable option, we don't need to capture this information in the type.
This means we can replace the description node with a simple text node.

Simplify types: Remove Replace LiquidDocParamDescription with TextNode

Now that the param description is configurable, this isn't needed

Author: jamesmengo

packages/liquid-html-parser/src/stage-1-cst.ts

@@ -111,16 +111,10 @@ export interface ConcreteLiquidDocParamNode
   extends ConcreteBasicNode<ConcreteNodeTypes.LiquidDocParamNode> {
   name: 'param';
   paramName: ConcreteTextNode;
-  paramDescription: ConcreteLiquidDocParamDescription | null;
+  paramDescription: ConcreteTextNode | null;
   paramType: ConcreteTextNode | null;
 }
 
-export interface ConcreteLiquidDocParamDescription
-  extends ConcreteBasicNode<ConcreteNodeTypes.TextNode> {
-  dashSeparated: boolean;
-  value: string;
-}
-
 export interface ConcreteHtmlNodeBase<T> extends ConcreteBasicNode<T> {
   attrList?: ConcreteAttributeNode[];
 }

packages/liquid-html-parser/src/stage-2-ast.spec.ts

@@ -1244,13 +1244,11 @@ describe('Unit: Stage 2 (AST)', () => {
       expectPath(ast, 'children.0.body.nodes.0.paramName.value').to.eql('asdf');
       expectPath(ast, 'children.0.body.nodes.0.paramDescription.type').to.eql('TextNode');
       expectPath(ast, 'children.0.body.nodes.0.paramDescription.value').to.eql('');
-      expectPath(ast, 'children.0.body.nodes.0.paramDescription.dashSeparated').to.eql(false);
       expectPath(ast, 'children.0.body.nodes.1.type').to.eql('LiquidDocParamNode');
       expectPath(ast, 'children.0.body.nodes.1.name').to.eql('@param');
       expectPath(ast, 'children.0.body.nodes.1.paramName.type').to.eql('TextNode');
       expectPath(ast, 'children.0.body.nodes.1.paramName.value').to.eql('paramWithDescription');
       expectPath(ast, 'children.0.body.nodes.1.paramDescription.type').to.eql('TextNode');
-      expectPath(ast, 'children.0.body.nodes.1.paramDescription.dashSeparated').to.eql(true);
       expectPath(ast, 'children.0.body.nodes.1.paramDescription.value').to.eql(
         'param with description and `punctation`. This is still a valid param description.',
       );

packages/liquid-html-parser/src/stage-2-ast.ts

@@ -73,7 +73,6 @@ import {
   LiquidHtmlConcreteNode,
   ConcreteLiquidTagBaseCase,
   ConcreteLiquidTagContentForMarkup,
-  ConcreteLiquidDocParamDescription,
 } from './stage-1-cst';
 import { Comparators, NamedTags, NodeTypes, nonTraversableProperties, Position } from './types';
 import { assertNever, deepGet, dropLast } from './utils';
@@ -762,19 +761,10 @@ export interface LiquidDocParamNode extends ASTNode<NodeTypes.LiquidDocParamNode
   /** The name of the parameter (e.g. "product") */
   paramName: TextNode;
   /** Optional description of the parameter in a Liquid doc comment (e.g. "The product title") */
-  paramDescription: LiquidDocParamDescription | null;
+  paramDescription: TextNode | null;
   /** Optional type annotation for the parameter (e.g. "{string}", "{number}") */
   paramType: TextNode | null;
 }
-
-export interface LiquidDocParamDescription extends ASTNode<NodeTypes.TextNode> {
-  /** Whether the parameter description is dash-separated (e.g. "paramName - paramDescription") */
-  dashSeparated: boolean;
-
-  /** The body of the description */
-  value: string;
-}
-
 export interface ASTNode<T> {
   /**
    * The type of the node, as a string.
@@ -1301,8 +1291,8 @@ function buildAst(
             position: position(node.paramName),
             source: node.paramName.source,
           },
-          paramDescription: toParamDescription(node.paramDescription),
-          paramType: toParamType(node.paramType),
+          paramDescription: toNullableTextNode(node.paramDescription),
+          paramType: toNullableTextNode(node.paramType),
         });
         break;
       }
@@ -1983,6 +1973,11 @@ function toHtmlSelfClosingElement(
   };
 }
 
+function toNullableTextNode(node: ConcreteTextNode | null): TextNode | null {
+  if (!node) return null;
+  return toTextNode(node);
+}
+
 function toTextNode(node: ConcreteTextNode): TextNode {
   return {
     type: NodeTypes.TextNode,
@@ -2087,26 +2082,3 @@ function getUnclosed(node?: ParentNode, parentNode?: ParentNode): UnclosedNode |
     blockStartPosition: 'blockStartPosition' in node ? node.blockStartPosition : node.position,
   };
 }
-
-function toParamDescription(
-  node: ConcreteLiquidDocParamDescription | null,
-): LiquidDocParamDescription | null {
-  if (!node) return null;
-  return {
-    type: NodeTypes.TextNode,
-    value: node.value,
-    position: position(node),
-    source: node.source,
-    dashSeparated: node.dashSeparated,
-  };
-}
-
-function toParamType(node: ConcreteTextNode | null): TextNode | null {
-  if (!node) return null;
-  return {
-    type: NodeTypes.TextNode,
-    value: node.value,
-    position: position(node),
-    source: node.source,
-  };
-}

packages/prettier-plugin-liquid/src/plugin.ts

@@ -61,6 +61,13 @@ const options: SupportOptions = {
     description: 'Indent the contents of the {% schema %} tag',
     since: '0.1.0',
   },
+  liquidDocParamDash: {
+    type: 'boolean',
+    category: 'LIQUID',
+    default: true,
+    description: 'Append a dash (-) to separate descriptions in {% doc %} @param annotations',
+    since: '1.6.4',
+  },
 };
 
 const defaultOptions = {

packages/prettier-plugin-liquid/src/printer/print/liquid.ts

@@ -508,7 +508,7 @@ export function printLiquidDoc(
 
 export function printLiquidDocParam(
   path: AstPath<LiquidDocParamNode>,
-  _options: LiquidParserOptions,
+  options: LiquidParserOptions,
   _print: LiquidPrinter,
   _args: LiquidPrinterArgs,
 ): Doc {
@@ -525,7 +525,8 @@ export function printLiquidDocParam(
 
   if (node.paramDescription?.value) {
     const normalizedDescription = node.paramDescription.value.replace(/\s+/g, ' ').trim();
-    if (node.paramDescription.dashSeparated) {
+
+    if (options.liquidDocParamDash) {
       parts.push(' - ', normalizedDescription);
     } else {
       parts.push(' ', normalizedDescription);

packages/prettier-plugin-liquid/src/test/liquid-doc/fixed.liquid

@@ -1,29 +1,29 @@
 It should indent the body
 {% doc %}
-  @param paramName param with description
-{% enddoc %}
-
-It should not dedent to root
-{% doc %}
-  @param paramName param with description
+  @param paramName - param with description
 {% enddoc %}
 
 It should trim whitespace between nodes
 {% doc %}
-  @param paramName param with description
+  @param paramName - param with description
 {% enddoc %}
 
-It should format the param type
+It should normalize the param type
 {% doc %}
-  @param {string} paramName param with description
+  @param {string} paramName - param with description
 {% enddoc %}
 
 It should format the param description with a dash separator
 {% doc %}
   @param paramName - param with description
 {% enddoc %}
 
-It should normalize the param description
+It should respect the liquidDocParamDash option liquidDocParamDash: false
 {% doc %}
   @param paramName param with description
 {% enddoc %}
+
+It should normalize the param description
+{% doc %}
+  @param paramName - param with description
+{% enddoc %}

packages/prettier-plugin-liquid/src/test/liquid-doc/index.liquid

@@ -1,30 +1,29 @@
 It should indent the body
 {% doc %}
-@param paramName param with description
+  @param paramName - param with description
 {% enddoc %}
 
-It should not dedent to root
+It should trim whitespace between nodes
 {% doc %}
-@param paramName param with description
+  @param paramName - param with description
 {% enddoc %}
 
-It should trim whitespace between nodes
+It should normalize the param type
 {% doc %}
-@param paramName param with description
+  @param { string     } paramName - param with description
 {% enddoc %}
 
-It should format the param type
+It should format the param description with a dash separator
 {% doc %}
-@param { string } paramName param with description
+  @param paramName  -   param with description
 {% enddoc %}
 
-It should format the param description with a dash separator
+It should respect the liquidDocParamDash option liquidDocParamDash: false
 {% doc %}
-@param paramName  -   param with description
+  @param paramName  param with description
 {% enddoc %}
 
 It should normalize the param description
 {% doc %}
-@param paramName param          with                    description
+  @param paramName - param           with                    description
 {% enddoc %}
-

packages/prettier-plugin-liquid/src/types.ts

@@ -24,6 +24,7 @@ export type LiquidParserOptions = ParserOptions<LiquidHtmlNode> & {
   embeddedSingleQuote: boolean;
   indentSchema: boolean;
   captureWhitespaceSensitivity: 'strict' | 'ignore';
+  liquidDocParamDash: boolean;
 };
 export type LiquidPrinterArgs = {
   leadingSpaceGroupId?: symbol[] | symbol;