Include usage documentations in JSDoc

[mohsen1]

All types have nice usage docs. Would be nice to have them in JSDoc to show up in text editors.

[piotrwitek]

That's interesting idea. What are the best practices to implement that, can you link to some examples?

The main concern is maintainability of these JSDoc comments, like for example when we update usage examples they should stay up to date.

[mohsen1]

You probably want to use the JSDoc as the source of truth and then use tools like tsdoc to generate your README and/or website from it.

[IssueHuntBot]

@issuehuntfest has funded $20.00 to this issue. See it on IssueHunt

[rahgurung]

@mohsen1 @piotrwitek I would like to take this, can you get me started please.

[piotrwitek]

@gurungrahul2 That's awesome!

1. First step would be to copy all the examples from README to the source files like this (note I removed import and moved "Expect" on top):

/**
 * SetIntersection (same as Extract)
 * @desc Set intersection of given union types `A` and `B`
 * @example
 * ```
 * // Expect: "2" | "3"
 * type ResultSet = SetIntersection<'1' | '2' | '3', '2' | '3' | '4'>;
 * // Expect: () => void
 * type ResultSetMixed = SetIntersection<string | number | (() => void), Function>;
 * ```
 */
export type SetIntersection<A, B> = A extends B ? A : never;

2. Second step is to parse source files to generate a markdown based docs static website. One way is to use a full documentation generator to generate a website from source files (I'm open to suggestions if you can find something but I guess TypeScript support will be required, maybe this: https://dotnet.github.io/docfx/).
   Another way would be to use simple JSDoc => Markdown (like jsdoc2md) converter and then use it as a page in a markdown docs generator like Docsaurus.

Additional finds:

• https://github.com/onury/docma
• https://github.com/docsifyjs/docsify/ -> looks nice and this TS project is using it so we might check their solution https://github.com/romakita/ts-express-decorators

Now notice that this issue is only about (1).
For (2) we have a separate issue that you're free to pick-up later if you want: #30

Let me know what you think!

[rahgurung]

@piotrwitek I am working on 1, and I will take 2 after it, I will ping you if I have queries, on it.

[piotrwitek]

@gurungrahul2 that's cool! Let me know when you'll be approaching (2), I'll try to help as much as I can.

[mohsen1]

note that the JSDoc markdown doesn't support triple backtick code blocks. You must indent code blocks.

[piotrwitek]

@mohsen1 could you be more specific about what are you referring to? is it @example directive or what?

[mohsen1]

JSDoc is not that well specified but in most tools I have used the triple backtick was not working. It's not specific to a single directive like @example.

[piotrwitek]

Thanks @mohsen1, I got it now.

[IssueHuntBot]

@piotrwitek has rewarded $14.00 to @gurungrahul2. See it on IssueHunt

• 💰 Total deposit: $20.00
• 🎉 Repository reward(20%): $4.00
• 🔧 Service fee(10%): $2.00