Add punctuation support in LiquidDoc param descriptions

Shopify · Jan 7, 2025 · 2e520af · 2e520af
1 parent 4d6c5e4
commit 2e520af
Show file tree

Hide file tree

Showing 3 changed files with 13 additions and 3 deletions.
diff --git a/packages/liquid-html-parser/grammar/liquid-html.ohm b/packages/liquid-html-parser/grammar/liquid-html.ohm
@@ -398,7 +398,8 @@ LiquidDoc <: Helpers {
   paramNode = "@param" space* (paramType)? space* (paramName)? space* "-"? paramDescription?
   paramType = "{" anyExceptStar<"}"> "}"
   paramName = identifierCharacter+
-  paramDescription = (~newline identifierCharacter | space)+
+  paramDescription = (~newline identifierCharacter | space | punctuation)+
+  punctuation = singleQuote | doubleQuote | "." | "`"
 }
 
 LiquidHTML <: Liquid {

diff --git a/packages/liquid-html-parser/src/stage-1-cst.spec.ts b/packages/liquid-html-parser/src/stage-1-cst.spec.ts
@@ -1071,6 +1071,15 @@ describe('Unit: Stage 1 (CST)', () => {
           expectPath(cst, '0.children.2.paramDescription.dashSeparated').to.equal(false);
         });
 
+        it('should accept punctation inside the param description body', () => {
+          const testStr = `{% doc %} @param paramName paramDescription - asdf . \`should\` work {% enddoc %}`;
+          cst = toCST(testStr);
+
+          expectPath(cst, '0.children.0.paramDescription.value').to.equal(
+            'paramDescription - asdf . `should` work',
+          );
+        });
+
         it('should parse unsupported doc tags as text nodes', () => {
           const testStr = `{% doc %} @unsupported this tag is not supported {% enddoc %}`;
           cst = toCST(testStr);

diff --git a/packages/liquid-html-parser/src/stage-2-ast.spec.ts b/packages/liquid-html-parser/src/stage-2-ast.spec.ts
@@ -1232,7 +1232,7 @@ describe('Unit: Stage 2 (AST)', () => {
       ast = toLiquidAST(`
         {% doc -%}
         @param asdf
-        @param {String} paramWithDescription - param with description
+        @param {String} paramWithDescription - param with description and \`punctation\`. This is still a valid param description.
         @unsupported this node falls back to a text node
         {%- enddoc %}
       `);
@@ -1252,7 +1252,7 @@ describe('Unit: Stage 2 (AST)', () => {
       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',
+        'param with description and `punctation`. This is still a valid param description.',
       );
       expectPath(ast, 'children.0.body.nodes.1.paramType.type').to.eql('TextNode');
       expectPath(ast, 'children.0.body.nodes.1.paramType.value').to.eql('String');