feat: jsdoc tweaks (#6)

ScottLogic · Jan 4, 2023 · ab4583d · ab4583d
1 parent b63b163
commit ab4583d
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 17 deletions.
diff --git a/helpers/docComment.js b/helpers/docComment.js
@@ -0,0 +1,5 @@
+const indent = (text) =>
+  // add a star before each newline and the start of the string
+  text.replace(/^/gm, " * ");
+
+module.exports = indent;
diff --git a/partials/model.handlebars b/partials/model.handlebars
@@ -1,8 +1,11 @@
-{{#if description}}
 /**
- * {{description}}
+ * {{@key}}
+ {{#if description}}* {{description}}{{/if~}}
+ *
+ {{#each properties}}
+ * @param { {{~typeConvert this~}} } {{#if _required}}{{@key}}{{else}}[{{@key}}]{{/if}} {{#if description}} - {{description}}{{/if}}
+ {{/each}}
  */
-{{/if}}
 class {{@key}} {
 
   static propertyTypes =  [
@@ -15,9 +18,6 @@ class {{@key}} {
   ];
 
   {{#each properties}}
-    {{#if description}}
-    // {{description}}
-    {{/if}}
     {{@key}};
   {{/each}}
 }
diff --git a/template/api.js.handlebars b/template/api.js.handlebars
@@ -5,14 +5,12 @@ const request = require("./request");
 const ParameterBuilder = require("./parameterBuilder");
 const { deserialize, serialize } = require("./serializer");
 
-/*
-{{_info.title}}
-{{info.description}}
-Version: {{info.version}}
-*/
-
-{{#if _tag.description}}// {{_tag.description}}{{/if}}
-
+/**
+ * {{_info.title}}
+ *
+{{#if info.description}}{{docComment info.description}}{{/if}}
+{{#if info.version}} * @version {{info.version}}{{/if}}
+ */
 class Api{{_tag.name}} {
 
   constructor(config) {
@@ -24,11 +22,20 @@ class Api{{_tag.name}} {
   {{#each this}}
     {{#ifEquals ../../_tag.name _tag.name}}
 
-      {{#if summary}}// {{summary}}{{/if}}
-      {{#if description}}// {{description}}{{/if}}
+      /** 
+      {{#if summary}}
+       * {{summary}}
+       * 
+      {{/if}}
+      {{#if description}}
+       * {{description}}
+       *
+      {{/if}}
+      {{#if tags}} * @tags {{tags}}{{/if}}
       {{#each _sortedParameters}}
-        // @param {{name}} {{description}}
+       * @param { {{~typeConvert schema ../../../_options~}} } {{name}} {{description}}
       {{/each}}
+      */
       async {{operationId}}(
         {{#each _sortedParameters}}
           {{name}}

diff --git a/template/model.js.handlebars b/template/model.js.handlebars
@@ -1,9 +1,11 @@
 {{#each components.schemas}}
 {{> model}}
+
 {{/each}}
 
 {{#each components.inlineObjects}}
 {{> model}}
+
 {{/each}}
 
 const models = [