Add formatting support for optional liquidDoc params

----
- Preserve `[]` delimiteres
- Strips whitespace between delimiter and param name

Author: jamesmengo

.changeset/olive-cougars-float.md

@@ -0,0 +1,6 @@
+---
+'@shopify/prettier-plugin-liquid': minor
+---
+
+Add formatting support for optional liquidDoc parameters (e.g. `@param [optional-parameter] - paramDescription`).
+Whitespace is now stripped around the parameter name and the optional delimiters.

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

@@ -520,8 +520,10 @@ export function printLiquidDocParam(
     parts.push(' ', `{${node.paramType.value}}`);
   }
 
-  if (node.paramName.value) {
+  if (node.required) {
     parts.push(' ', node.paramName.value);
+  } else {
+    parts.push(' ', `[${node.paramName.value}]`);
   }
 
   if (node.paramDescription?.value) {

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

@@ -19,6 +19,7 @@ It should format the param description with a dash separator
 {% enddoc %}
 
 It should respect the liquidDocParamDash option liquidDocParamDash: false
+liquidDocParamDash: false
 {% doc %}
   @param paramName param with description
 {% enddoc %}
@@ -28,6 +29,19 @@ It should normalize the param description
   @param paramName - param with description
 {% enddoc %}
 
+It should strip whitespace between optional param delimiters
+{% doc %}
+  @param [paramName] - param with description
+{% enddoc %}
+
+It should not break params with malformed optional delimiters
+{% doc %}
+  @param [missingTail - param with description
+  @param missingHead - ] - param with description
+  @param [too many words no desc]
+  @param [too many words] - param with description
+{% enddoc %}
+
 It should push example content to the next line
 {% doc %}
   @example
@@ -37,20 +51,16 @@ It should push example content to the next line
 It should allow single empty lines between content
 {% doc %}
   @example
-
   This is a valid example
 
-  So is this without a newline
-  See?
+  So is this without a newline See?
 {% enddoc %}
 
 It should allow multiple empty lines between content
 {% doc %}
   @example
-
   This is a valid example
 
-
   Here is another example
 
   with a single empty line
@@ -59,14 +69,12 @@ It should allow multiple empty lines between content
 It should remove empty lines at the end of the content
 {% doc %}
   @example
-
   Here is my content and a newline
 {% enddoc %}
 
 It should respect example content with param and description
 {% doc %}
   @param paramName - param with description
   @example
-
   This is a valid example
 {% enddoc %}

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

@@ -10,22 +10,36 @@ It should trim whitespace between nodes
 
 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
+  @param paramName - param with description
 {% enddoc %}
 
 It should respect the liquidDocParamDash option liquidDocParamDash: false
+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 %}
+
+It should strip whitespace between optional param delimiters
+{% doc %}
+  @param [ paramName ] - param with description
+{% enddoc %}
+
+It should handle params with malformed optional delimiters
+{% doc %}
+  @param [missingTail - param with description
+  @param missingHead - ] - param with description
+  @param [too many words no desc]
+  @param [too many words] - param with description
 {% enddoc %}
 
 It should push example content to the next line
@@ -36,20 +50,16 @@ It should push example content to the next line
 It should allow single empty lines between content
 {% doc %}
   @example
-
   This is a valid example
 
-  So is this without a newline
-  See?
+  So is this without a newline See?
 {% enddoc %}
 
 It should allow multiple empty lines between content
 {% doc %}
   @example
-
   This is a valid example
 
-
   Here is another example
 
   with a single empty line
@@ -58,15 +68,12 @@ It should allow multiple empty lines between content
 It should remove empty lines at the end of the content
 {% doc %}
   @example
-
   Here is my content and a newline
-
 {% enddoc %}
 
 It should respect example content with param and description
 {% doc %}
-@param paramName - param with description
-@example
-
-This is a valid example
+  @param paramName - param with description
+  @example
+  This is a valid example
 {% enddoc %}