From a4793cfd2ef1aac4f3f28b448e9e7f19e4ae9117 Mon Sep 17 00:00:00 2001
From: Hugo Dias <hugomrdias@gmail.com>
Date: Fri, 20 Nov 2020 11:26:11 +0000
Subject: [PATCH] fix: more ts docs and include private and protected in docs
 (#678)

---
 cmds/ts.js      |  8 +-------
 md/ts-jsdoc.md  | 36 +++++++++++++++++++++++++++++++++++-
 src/ts/index.js |  4 ++--
 3 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/cmds/ts.js b/cmds/ts.js
index ac1a03665..0ec8ac079 100644
--- a/cmds/ts.js
+++ b/cmds/ts.js
@@ -8,13 +8,7 @@ Presets:
 \`config\`      Prints base config to stdout.
 
 Note: 
-To provide users types declarations with 0-configuration add following to package.json:
-
-\`\`\`json
-"typesVersions": {
-  "*": { "src/*": ["dist/src/*", "dist/src/*/index"] }
-},
-\`\`\`
+Check out the documentation for JSDoc based TS types here: https://github.com/ipfs/aegir/blob/master/md/ts-jsdoc.md
 
 Supports options forwarding with '--' for more info check https://www.typescriptlang.org/docs/handbook/compiler-options.html
 `
diff --git a/md/ts-jsdoc.md b/md/ts-jsdoc.md
index a77df9801..9591bbe2d 100644
--- a/md/ts-jsdoc.md
+++ b/md/ts-jsdoc.md
@@ -9,6 +9,7 @@ aegir ts -p config > tsconfig.json
 
 Add types configuration to your package.json:
 ```json
+"types": "dist/src/index.d.ts",
 "typesVersions": {
   "*": { "src/*": ["dist/src/*", "dist/src/*/index"] }
 },
@@ -29,7 +30,9 @@ Presets:
 `docs`        Generates documentation based on type declarations to the `docs` folder.
 `config`      Prints base config to stdout.
 ```
+## Github Action
 
+To run the typechecker in the CI you can use this action https://github.com/Gozala/typescript-error-reporter-action and you will get the errors reported inline with the code. 
 
 ## Adding types with JSDoc
 
@@ -91,7 +94,7 @@ exports.IPFS = IPFS
 ```
 
 #### 3. Use a `types.ts` file
-When writing types sometimes JSDoc can be cumbersome, impossible, it can output weird type declarations or even broken documentation. Most of these problems can be solved by defining some complex types in typescript in a `types.ts` file.
+When writing types JSDoc can sometimes be cumbersome, impossible, it can output weird type declarations or even broken documentation. Most of these problems can be solved by defining some complex types in typescript in a `types.ts` file.
 
 ```ts
 // types.ts
@@ -102,4 +105,35 @@ export type IntersectionType = Type1 & Type2
 // index.js
 /** @type { import('./types').IntersectionType } */
 const list
+```
+
+#### 4. JSDoc comments bad parsing
+Some TS tooling may have problems parsing comments if they are not very well divided.
+
+```ts
+
+// BAD - the base typedef can be parsed as a comment for Square
+
+/** @typedef {import('./index') Base} Base */
+
+class Square {}
+
+
+// GOOD 
+/** @typedef {import('./index') Base} Base */
+
+/**
+ * Cool Square class
+ * @class
+ */
+class Square {}
+
+// GOOD
+
+class Square {}
+
+module.export = Square
+
+/** @typedef {import('./index') Base} Base */
+
 ```
\ No newline at end of file
diff --git a/src/ts/index.js b/src/ts/index.js
index 904d1a474..4be49f792 100644
--- a/src/ts/index.js
+++ b/src/ts/index.js
@@ -145,8 +145,8 @@ const docs = async (forwardOptions, extraInclude) => {
         '--excludeExternals',
         // '--excludeNotDocumented',
         // '--excludeNotExported',
-        '--excludePrivate',
-        '--excludeProtected',
+        // '--excludePrivate',
+        // '--excludeProtected',
         '--includeDeclarations',
         '--hideGenerator',
         '--includeVersion',