simple custom tags support

gillyspy · Jun 4, 2022 · 6b052bd · 6b052bd
1 parent 6e797e8
commit 6b052bd
Show file tree

Hide file tree

Showing 2 changed files with 121 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,20 @@
 # @suitegeezus/docdash-suitescript
-Docdash but enhanced to recognize [SuiteScript's JsDoc tags](https://docs.oracle.
-com/en/cloud/saas/netsuite/ns-online-help/chapter_4387175355.html):
+Docdash but enhanced: 
+- to recognize [SuiteScript's JsDoc tags](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_4387175355.html)
+- Support for basic custom tags
+
+
+## SuiteScript JsDoc supported tags
 - NApiVersion
 - NModuleScope
 - NScriptType
 - [NAmdConfig](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4704111062.html)
+
+## Additional Tags
 - governance - arbitrary
 - appliestorecord - arbitrary
 
+## Basic Configuration 
 You will need to:
 1. inform jsdoc of these tags by adding the following in your jsdoc config plugins.
 ```json
@@ -19,12 +26,46 @@ const template = path.dirname(require.resolve('@suitegeezus/docdash-suitescript'
 // other code and config here
 Object.assign( jsdocConfig.opts, {template });  
 ```
-
 ### Screenshot
 
 ![SuiteScript Doc'd](https://raw.githubusercontent.com/gillyspy/docdash-suitescript/master/.README_images/ba320f52.png)
 ![SuiteScript example](https://raw.githubusercontent.com/gillyspy/docdash-suitescript/master/.README_images/5d0af3da.png)
 
+## Custom Tags
+Displaying custom tags in docs is usually the easy part but getting it into the template is difficult. So this will do 
+basic support of custom tag. All you have to do is create a script with a few lines and put it somewhere jsdoc can find. 
+
+1. Write a script (e.g. `customTags.js`) that contains something like this: 
+```js
+// customTags.js
+exports.defineTags = function (dictionary) {
+  dictionary.defineTag('kwijibo', {
+    'mustHaveValue': true,
+    canHaveType    : false,
+    canHaveName    : false,
+    'onTagged'     : function (doclet, tag) {
+
+      doclet.kwijibo = tag.value;
+
+      if (!doclet.meta) {
+        doclet.meta = {};
+      }
+      // the customTagName must match the doclet key and tag above
+      doclet.meta.customTagName = 'kwijibo';
+    }
+  })
+          // optional synonym
+    .synonym('mycustom');
+}; 
+```
+2. put this script somewhere jsdoc can see it. (probably easiest thing would be to 
+   copy it to the jsdoc/plugins folder)
+3. Refer to this script via plugins (in your jsdoc.conf)
+```json
+"plugins": ["@suitegeezus/docdash-suitescript/ssTags", "from/a/root/jsdoc/can/resolve/customTags"]
+```
+
+
 
 # Docdash
 [![Build Status](https://api.travis-ci.org/clenemt/docdash.png?branch=master)](https://travis-ci.org/clenemt/docdash) [![npm version](https://badge.fury.io/js/docdash.svg)](https://badge.fury.io/js/docdash) [![license](https://img.shields.io/npm/l/docdash.svg)](LICENSE.md)

diff --git a/tmpl/details.tmpl b/tmpl/details.tmpl
@@ -2,9 +2,11 @@
 var data = obj;
 var self = this;
 var defaultObjectClass = '';
+var isDocked = false;
 
 // Check if the default value is an object or array; if so, apply code highlighting
 if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvaluetype === 'array')) {
+    isDocked = true;
     try {
         var indentedValues = JSON.stringify(JSON.parse(data.defaultvalue), null, '  ');
         data.defaultvalue = indentedValues;
@@ -15,43 +17,57 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
 ?>
 
 <dl class="details">
-    <?js if (data.description) {?>
+    <?js if (data.description) {
+        isDocked = true;
+    ?>
     <dt class="tag-description">Description:</dt>
     <dd class="tag-description"><ul class="dummy"><li><?js= data.description ?></li></ul></dd>
     <?js } ?>
 
-    <?js if (data.meta && self.outputSourceFiles) {?>
+    <?js if (data.meta && self.outputSourceFiles) {
+        isDocked = true;
+    ?>
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
         <?js= self.linkto(meta.shortpath) ?>, <?js= self.linkto(meta.shortpath, 'line ' + meta.lineno, null, 'line' + meta.lineno) ?>
     </li></ul></dd>
     <?js } ?>
 
-    <?js if (data.version) {?>
+    <?js if (data.version) {
+        isDocked = true;
+    ?>
     <dt class="tag-version">Version:</dt>
     <dd class="tag-version"><ul class="dummy"><li><?js= version ?></li></ul></dd>
     <?js } ?>
 
-    <?js if (data.since) {?>
+    <?js if (data.since) {
+        isDocked = true;
+    ?>
     <dt class="tag-since">Since:</dt>
     <dd class="tag-since"><ul class="dummy"><li><?js= since ?></li></ul></dd>
     <?js } ?>
 
-    <?js if (data.inherited && data.inherits && !data.overrides) { ?>
+    <?js if (data.inherited && data.inherits && !data.overrides) {
+        isDocked = true;
+     ?>
     <dt class="inherited-from">Inherited From:</dt>
     <dd class="inherited-from"><ul class="dummy"><li>
         <?js= this.linkto(data.inherits, this.htmlsafe(data.inherits)) ?>
     </li></ul></dd>
     <?js } ?>
 
-    <?js if (data.overrides) { ?>
+    <?js if (data.overrides) {
+        isDocked = true;
+    ?>
     <dt class="tag-overrides">Overrides:</dt>
     <dd class="tag-overrides"><ul class="dummy"><li>
         <?js= this.linkto(data.overrides, this.htmlsafe(data.overrides)) ?>
     </li></ul></dd>
     <?js } ?>
 
-    <?js if (data.implementations && data.implementations.length) { ?>
+    <?js if (data.implementations && data.implementations.length) {
+        isDocked = true;
+    ?>
     <dt class="implementations">Implementations:</dt>
     <dd class="implementations"><ul>
         <?js data.implementations.forEach(function(impl) { ?>
@@ -60,7 +76,9 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
     </ul></dd>
     <?js } ?>
 
-    <?js if (data.implements && data.implements.length) { ?>
+    <?js if (data.implements && data.implements.length) {
+        isDocked = true;
+    ?>
     <dt class="implements">Implements:</dt>
     <dd class="implements"><ul>
         <?js data.implements.forEach(function(impl) { ?>
@@ -69,7 +87,9 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
     </ul></dd>
     <?js } ?>
 
-    <?js if (data.mixes && data.mixes.length) { ?>
+    <?js if (data.mixes && data.mixes.length) {
+        isDocked = true;
+    ?>
         <dt class="mixes">Mixes In:</dt>
 
         <dd class="mixes"><ul>
@@ -79,14 +99,18 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
         </ul></dd>
     <?js } ?>
 
-    <?js if (data.deprecated) { ?>
+    <?js if (data.deprecated) {
+        isDocked = true;
+    ?>
         <dt class="important tag-deprecated">Deprecated:</dt><?js
             if (data.deprecated === true) { ?><dd class="yes-def tag-deprecated"><ul class="dummy"><li>Yes</li></ul></dd><?js }
             else { ?><dd><ul class="dummy"><li><?js= data.deprecated ?></li></ul></dd><?js }
         ?>
     <?js } ?>
 
-    <?js if (data.author && author.length) {?>
+    <?js if (data.author && author.length) {
+        isDocked = true;
+    ?>
     <dt class="tag-author">Author:</dt>
     <dd class="tag-author">
         <ul><?js author.forEach(function(a) { ?>
@@ -95,40 +119,54 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
     </dd>
     <?js } ?>
 
-    <?js if (data.copyright) {?>
+    <?js if (data.copyright) {
+        isDocked = true;
+    ?>
     <dt class="tag-copyright">Copyright:</dt>
     <dd class="tag-copyright"><ul class="dummy"><li><?js= copyright ?></li></ul></dd>
     <?js } ?>
 
-    <?js if (data.license) {?>
+    <?js if (data.license) {
+        isDocked = true;
+    ?>
     <dt class="tag-license">License:</dt>
     <dd class="tag-license"><ul class="dummy"><li><?js= license ?></li></ul></dd>
     <?js } ?>
 
     <!-- Render NetSuite module data -->
 
 
-    <?js if (data.NApiVersion) {?>
+    <?js if (data.NApiVersion) {
+        isDocked = true;
+    ?>
     <dt class="tag-namdconfig">Require Configuration:</dt>
     <dd class="tag-namdconfig"><ul class="dummy"><li><?js= NAmdConfig ?></li></ul></dd>
     <?js } ?>
 
-    <?js if (data.NApiVersion) {?>
+    <?js if (data.NApiVersion) {
+        isDocked = true;
+    ?>
     <dt class="tag-napiversion">API Version:</dt>
     <dd class="tag-napiversion"><ul class="dummy"><li><?js= NApiVersion ?></li></ul></dd>
     <?js } ?>
 
-    <?js if (data.NScriptType) {?>
+    <?js if (data.NScriptType) {
+        isDocked = true;
+    ?>
     <dt class="tag-nscripttype">Script Type:</dt>
     <dd class="tag-nscripttype"><ul class="dummy"><li><?js= NScriptType ?></li></ul></dd>
     <?js } ?>
 
-    <?js if (data.NModuleScope) {?>
+    <?js if (data.NModuleScope) {
+        isDocked = true;
+    ?>
     <dt class="tag-nmodulescope">Module Scope:</dt>
     <dd class="tag-nmodulescope"><ul class="dummy"><li><?js= NModuleScope ?></li></ul></dd>
     <?js } ?>
 
-    <?js if (data.appliedtorecord && appliedtorecord.length) {?>
+    <?js if (data.appliedtorecord && appliedtorecord.length) {
+        isDocked = true;
+    ?>
     <dt class="tag-appliedtorecord">Applied to Records:</dt>
     <dd class="tag-appliedtorecord">
         <ul><?js appliedtorecord.forEach(function(a) { ?>
@@ -139,14 +177,18 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
 
     <!-- end NetSuite module data -->
 
-    <?js if (data.defaultvalue) {?>
+    <?js if (data.defaultvalue) {
+        isDocked = true;
+    ?>
     <dt class="tag-default">Default Value:</dt>
     <dd class="tag-default"><ul class="dummy">
             <li<?js= defaultObjectClass ?>><?js= data.defaultvalue ?></li>
         </ul></dd>
     <?js } ?>
 
-    <?js if (data.tutorials && tutorials.length) {?>
+    <?js if (data.tutorials && tutorials.length) {
+        isDocked = true;
+    ?>
     <dt class="tag-tutorial">Tutorials:</dt>
     <dd class="tag-tutorial">
         <ul><?js tutorials.forEach(function(t) { ?>
@@ -155,7 +197,9 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
     </dd>
     <?js } ?>
 
-    <?js if (data.see && see.length) {?>
+    <?js if (data.see && see.length) {
+        isDocked = true;
+    ?>
     <dt class="tag-see">See:</dt>
     <dd class="tag-see">
         <ul><?js see.forEach(function(s) { ?>
@@ -164,19 +208,30 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
     </dd>
     <?js } ?>
 
-    <?js if (data.todo && todo.length) {?>
+    <?js if (data.todo && todo.length) {
+        isDocked = true;
+    ?>
     <dt class="tag-todo">To Do:</dt>
     <dd class="tag-todo">
         <ul><?js todo.forEach(function(t) { ?>
             <li><?js= t ?></li>
         <?js }); ?></ul>
     </dd>
     <?js } ?>
+
+    <!-- custom tags here -->
+    <?js if(data.meta.customTagName){ ?>
+      <dt class="tag-unrecognized"><?js= data.meta.customTagName ?></dt>
+      <dd class="tag-unrecognized"><?js= data[data.meta.customTagName] ?></dd>
+    <?js } ?>
+
 </dl>
 
 <?js
     var properties = data.properties;
     if (properties && properties.length && properties.forEach) {
+        isDocked = true;
+
 ?>
 
     <h5 class="subsection-title">Properties:</h5>