Merge pull request #58 from webdoc-js/feature/inline-code-tags

[Feature]: Resolve {@code } tags

Author: ShukantPal

packages/webdoc-default-template/helper/renderer-plugins/signature.js

@@ -41,7 +41,7 @@ exports.signaturePlugin = {
             .map((param) =>
               param.identifier +
               (param.dataType ?
-                ": " + linker.linkTo(param.dataType) :
+                ": " + linker.linkTo(param.dataType, undefined, {htmlSafe: false}) :
                 ""
               ),
             )
@@ -51,26 +51,29 @@ exports.signaturePlugin = {
       if (doc.returns) {
         signature += ` → {${
           (doc.returns || [])
-            .map((returns) =>
-              (returns.dataType ? linker.linkTo(returns.dataType) : ""))
+            .map((returns) => (returns.dataType ?
+              linker.linkTo(returns.dataType, undefined, {htmlSafe: false}) :
+              ""))
             .join(", ")
         }} `;
       }
       break;
     case "PropertyDoc":
       if (doc.dataType) {
-        signature += ": " + linker.linkTo(doc.dataType);
+        signature += ": " + linker.linkTo(doc.dataType, undefined, {htmlSafe: false});
       }
       break;
     case "ClassDoc":
       if (doc.extends) {
         signature += ` extends ${
-          (doc.extends || []).map((superClass) => linker.linkTo(superClass)).join(", ")
+          (doc.extends || [])
+            .map((superClass) => linker.linkTo(superClass, undefined, {htmlSafe: false})).join(", ")
         }`;
       }
       if (doc.implements) {
         signature += `\nimplements ${
-          (doc.implements || []).map((ifc) => linker.linkTo(ifc)).join(", ")
+          (doc.implements || [])
+            .map((ifc) => linker.linkTo(ifc, undefined, {htmlSafe: false})).join(", ")
         }`;
       }
       break;

packages/webdoc-template-library/src/pipeline-elements/TemplateTagsResolver.js

@@ -3,6 +3,8 @@
 import type {TemplatePipeline, TemplatePipelineElement} from "../TemplatePipeline";
 import type {TemplateRenderer} from "../TemplateRenderer";
 
+const CODE_PATTERN = /{@code ([^}]*)}/g;
+
 const LINK_PATTERN = /{@link ([^|\s}]*)([\s|])?([^}]*)}/g;
 
 /**
@@ -28,12 +30,33 @@ export class TemplateTagsResolver implements TemplatePipelineElement<{}> {
   }
 
   run(input: string, pipelineData: any): string {
-    input = this.runLink(input);
+    input = this.runCodeTag(input);
+    input = this.runLinkTag(input);
+
+    return input;
+  }
+
+  runCodeTag(input: string): string {
+    const codePattern = CODE_PATTERN;
+
+    let codeMatch = codePattern.exec(input);
+
+    while (codeMatch) {
+      const code = codeMatch[1];
+      const startIndex = codeMatch.index;
+      const endIndex = codeMatch.index + codeMatch[0].length;
+
+      input = input.slice(0, startIndex) +
+        `<code>${code}</code>` +
+        input.slice(endIndex);
+
+      codeMatch = codePattern.exec(input);
+    }
 
     return input;
   }
 
-  runLink(input: string): string {
+  runLinkTag(input: string): string {
     const linkPattern = LINK_PATTERN;
     let linkMatch = linkPattern.exec(input);
 

packages/webdoc-template-library/src/template-plugins/LinkerPlugin.js

@@ -8,7 +8,8 @@ export type LinkOptions = {
   fragmentId?: string,
   linkMap?: Map<string, string>,
   monospace?: boolean,
-  shortenName?: boolean
+  shortenName?: boolean,
+  htmlSafe?: boolean
 };
 
 export type LinkerDocumentRecord = {
@@ -183,6 +184,7 @@ function LinkerPluginShell() {
      *  monospace font.
      * @param {boolean} options.shortenName - Indicates whether to extract the short name from the
      * longname and display the short name in the link text. Ignored if `linkText` is specified.
+     * @param {boolean}[options.htmlSafe=true]
      * @return {string} the HTML link, or the link text if the link is not available.
      */
     linkTo(docPath: any, linkText: string = docPath, options: LinkOptions = {}) {
@@ -193,9 +195,11 @@ function LinkerPluginShell() {
         return `<a href=${encodeURI(this.queryCache.get(docPath) || "")}>${linkText}</a>`;
       }
       if (isDataType(docPath)) {
-        let link = docPath.template
-          .replace(/</g, "&lt;")
-          .replace(/>/g, "&gt;");
+        let link = docPath.template;
+
+        if (options.htmlSafe !== false) {
+          link = link.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+        }
 
         for (let i = 1; i < docPath.length; i++) {
           link = link.replace(`%${i}`, this.linkTo(docPath[i], docPath[i], options));

packages/webdoc-template-library/test/pipeline-elements/TemplateTagsResolver.js

@@ -11,46 +11,52 @@ describe("@webdoc/template-library.TemplateTagsResolver", function() {
   mockTemplateRenderer.installPlugin("linker", LinkerPlugin);
   mockTagsResolver.attachTo({renderer: mockTemplateRenderer});
 
+  it("{@code Sample}", function() {
+    expect(mockTagsResolver.runCodeTag("--{@code Sample}--"))
+      .to.equal("--<code>Sample</code>--");
+  });
+
   it("{@link <DOC_PATH>}", function() {
-    expect(mockTagsResolver.runLink("--{@link <DOC_PATH>}--"))
+    expect(mockTagsResolver.runLinkTag("--{@link <DOC_PATH>}--"))
       .to.equal("--<DOC_PATH>--");
   });
 
   it("{@link <DOC_PATH> <NAME>}", function() {
-    expect(mockTagsResolver.runLink("--{@link <DOC_PATH> <NAME>}--"))
+    expect(mockTagsResolver.runLinkTag("--{@link <DOC_PATH> <NAME>}--"))
       .to.equal("--<NAME>--");
   });
 
   it("{@link <DOC_PATH>|<NAME>}", function() {
-    expect(mockTagsResolver.runLink("--{@link <DOC_PATH>|<NAME>}--"))
+    expect(mockTagsResolver.runLinkTag("--{@link <DOC_PATH>|<NAME>}--"))
       .to.equal("--<NAME>--");
   });
 
   it("{@link https://github.com/webdoc-js/webdoc}", function() {
-    expect(mockTagsResolver.runLink("--{@link https://github.com/webdoc-js/webdoc}--"))
+    expect(mockTagsResolver.runLinkTag("--{@link https://github.com/webdoc-js/webdoc}--"))
       .to.equal("--<a href=\"https://github.com/webdoc-js/webdoc\">" +
         "https://github.com/webdoc-js/webdoc</a>--");
   });
 
   it("{@link https://github.com/webdoc-js/webdoc|LINK_NAME}", function() {
-    expect(mockTagsResolver.runLink("--{@link https://github.com/webdoc-js/webdoc|LINK_NAME}--"))
+    expect(mockTagsResolver.runLinkTag("--{@link https://github.com/webdoc-js/webdoc|LINK_NAME}--"))
       .to.equal("--<a href=\"https://github.com/webdoc-js/webdoc\">" +
         "LINK_NAME</a>--");
   });
 
   it("{@link https://github.com/webdoc-js/webdoc LINK NAME}", function() {
-    expect(mockTagsResolver.runLink("--{@link https://github.com/webdoc-js/webdoc LINK NAME}--"))
+    expect(mockTagsResolver.runLinkTag("--{@link https://github.com/webdoc-js/webdoc LINK NAME}--"))
       .to.equal("--<a href=\"https://github.com/webdoc-js/webdoc\">" +
         "LINK NAME</a>--");
   });
 
   it("[LINK_TEXT]{@link DOC_PATH}", function() {
-    expect(mockTagsResolver.runLink("--[LINK_TEXT]{@link <DOC_PATH>}--"))
+    expect(mockTagsResolver.runLinkTag("--[LINK_TEXT]{@link <DOC_PATH>}--"))
       .to.equal("--LINK_TEXT--");
   });
 
   it("[LINK_TEXT]{@link https://github.com/webdoc-js/webdoc}", function() {
-    expect(mockTagsResolver.runLink("--[LINK_TEXT]{@link https://github.com/webdoc-js/webdoc}--"))
+    expect(
+      mockTagsResolver.runLinkTag("--[LINK_TEXT]{@link https://github.com/webdoc-js/webdoc}--"))
       .to.equal("--<a href=\"https://github.com/webdoc-js/webdoc\">" +
         "LINK_TEXT</a>--");
   });