feat: minor jsdoc tweaks

ScottLogic · Jan 4, 2023 · 7f29289 · 7f29289
1 parent b9905e1
commit 7f29289
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 19 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}}
 export class {{@key}} {
 
   static propertyTypes: Array<{name: string, type: string}> =  [
@@ -15,9 +18,6 @@ export class {{@key}} {
   ];
 
   {{#each properties}}
-    {{#if description}}
-    // {{description}}
-    {{/if}}
     public {{@key}}{{#unless _required}}?{{/unless}}: {{typeConvert this}};
   {{/each}}
-}
+}
diff --git a/template/api.ts.handlebars b/template/api.ts.handlebars
@@ -5,14 +5,12 @@ import { request } from "./request";
 import { Parameter, ParameterBuilder } from "./parameterBuilder";
 import { deserialize, serialize } from "./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}}
+ */
 export default class Api{{_tag.name}} {
   private config: Configuration;
 
@@ -25,12 +23,20 @@ export default class Api{{_tag.name}} {
   {{#each this}}
     {{#ifEquals ../../_tag.name _tag.name}}
 
-      {{#if summary}}// {{summary}}{{/if}}
-      {{#if description}}// {{description}}{{/if}}
-      {{#if tags}}// tags: {{tags}}{{/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}}{{#if _optional}}?{{/if}}:

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