fix: Need plugin to convert & to | when generating doc through jsdoc

jsdoc does not support & for intersection types and will never support it so we need a plugin to convert & to |. More information at https://github.com/chriseaton/jsdoc-plugin-intersection Or we could completely forgo jsdoc and use typescript tooling to generate our doc (this way, no incompatibility between jsdoc and typescript)
cozy · Mar 1, 2021 · 53faa64 · 53faa64
1 parent 0d1e099
commit 53faa64
Show file tree

Hide file tree

Showing 8 changed files with 19 additions and 7 deletions.
diff --git a/jsdoc.json b/jsdoc.json
@@ -0,0 +1,3 @@
+{
+    "plugins": ["jsdoc-plugin-intersection"]
+}
diff --git a/packages/cozy-client/package.json b/packages/cozy-client/package.json
@@ -47,6 +47,7 @@
     "btoa": "1.2.1",
     "cozy-logger": "1.6.0",
     "cozy-ui": "^34.0.0",
+    "jsdoc-plugin-intersection": "^1.0.4",
     "mockdate": "^2.0.2",
     "react": "16.13.1",
     "react-redux": "^7.2.0",

diff --git a/packages/cozy-client/src/models/document.js b/packages/cozy-client/src/models/document.js
@@ -30,11 +30,11 @@ export class Qualification {
     )
     if (qualification) {
       /**
-       * @type {string?} - The qualification label.
+       * @type {string?}
        */
       this.label = qualification.label
       /**
-       * @type {string?} - The document purpose.
+       * @type {string?}
        */
       this.purpose = attributes.purpose || qualification.purpose
       this.sourceCategory =

diff --git a/packages/cozy-client/types/cli/index.d.ts b/packages/cozy-client/types/cli/index.d.ts
@@ -23,5 +23,5 @@ export type DestroyableServer = any;
  * })
  * ```
  */
-export function createClientInteractive(clientOptions: object, serverOpts: any): Promise<any> | CozyClient;
+export function createClientInteractive(clientOptions: object, serverOpts: any): CozyClient | Promise<any>;
 import CozyClient from "../CozyClient";
diff --git a/packages/cozy-client/types/models/document.d.ts b/packages/cozy-client/types/models/document.d.ts
@@ -22,11 +22,11 @@ export class Qualification {
      */
     constructor(label: string, attributes?: QualificationAttributes);
     /**
-     * @type {string?} - The qualification label.
+     * @type {string?}
      */
     label: string | null;
     /**
-     * @type {string?} - The document purpose.
+     * @type {string?}
      */
     purpose: string | null;
     sourceCategory: string;

diff --git a/packages/cozy-client/types/types.d.ts b/packages/cozy-client/types/types.d.ts
@@ -9,7 +9,7 @@ export type ReduxStore = any;
 export type Token = any;
 export type ClientResponse = any;
 export type Manifest = any;
-export type QueryFetchStatus = "loading" | "loaded" | "pending" | "failed";
+export type QueryFetchStatus = "loading" | "loaded" | "failed" | "pending";
 export type QueryState = {
     id: string;
     definition: QueryDefinition;

diff --git a/scripts/docs.js b/scripts/docs.js
@@ -28,7 +28,10 @@ const main = async () => {
     }
     const pkgName = pkg.split('/')[1]
     const template = `{{>main}}`
-    const templateData = jsdoc2md.getTemplateDataSync({ files })
+    const templateData = jsdoc2md.getTemplateDataSync({
+      files,
+      configure: path.join(__dirname, '../', 'jsdoc.json')
+    })
     const output = jsdoc2md.renderSync({
       data: templateData,
       template: template

diff --git a/yarn.lock b/yarn.lock
@@ -7797,6 +7797,11 @@ jsdoc-parse@^5.0.0:
     sort-array "^4.1.1"
     test-value "^3.0.0"
 
+jsdoc-plugin-intersection@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/jsdoc-plugin-intersection/-/jsdoc-plugin-intersection-1.0.4.tgz#32ffe7f74df30ed1e86272c272856e0fd9aa9451"
+  integrity sha512-5OGv+aWpp0pYRMnhaUeqijesIi/xD2z8IIwIlK+JsQ0sXzMjiWT2YgNSvxcd476pRdh70Xmby/l7GD3NkWcKcQ==
+
 jsdoc-to-markdown@6:
   version "6.0.1"
   resolved "https://registry.yarnpkg.com/jsdoc-to-markdown/-/jsdoc-to-markdown-6.0.1.tgz#55640eea7a4f56fa9353316648bf0775531811ff"