Add tsdoc comments for Blitz functions inside VSCode

[michaelminhvo]

What do you want and why?

Currently developers have to rely on the blitz docs for documentation about function and parameter definitions. This means we have to context switch to the browser, visit the webpage, copy and paste the function name and use the search functionality.

We should use jsdocs to embed the documentation from the wiki inside VSCode.

For example pressing command and hovering over useRouter doesn't show anything in VSCode:

Here's how the Chakra functions look when we press command and hover:

Note the href will also save a lot of time as it links directly to the wiki.

Possible implementation(s)

Using jsdocs

[flybayer]

Great idea!

If you'd like to help contribute to this issue, make a PR that adds tsdoc comments to at least one of our blitz functions

You can add tsdoc comments to more than one function in a PR. But you only have to add at least one. This way everyone can contribute to this, vs one person having to do everything! :)

We'll keep this issue open until everything is sufficiently documented.

[JuanM04]

I'll leave this message for the near future: we should add a checkbox to the PR template that says something like "I updated the JSDocs if necessary"

[Lani]

If the purpose is to get descriptions for the IntelliSense in vs-code, then I would suggest following the TSDoc specification instead of JSDoc. Microsoft is behind TSDoc and has made real progress lately. They have created a good webpage that utlines some of the differences with JSDoc and why they created TSDoc: https://tsdoc.org/

They also have a nice playground where you can try out that the docs comments are parsed as you think that they are: https://tsdoc.org/play

Although JSDoc currently has more extensions for vs-code and more linting rules for es-lint, I think the built-in support in vs-code for renaming parameters etc is pretty good (most does however also work with JSDoc).

There also is a basic eslint-plugin for TSDoc that does some basic verification on the document format, I would suggest setting this up for the project as well.

It's really easy to set up, but if you want to quickly try it out I created a really basic example that has typedoc and eslint setup: https://github.com/Lani/tsdoc-typedoc-eslint-example

This is just a suggestion, and I can of course not see into the future if TSDoc really will take off, but I think soo 😃

[JuanM04]

@Lani I really like the idea of generating HTML documentation from TSDoc. We could generate documentation for blitzjs.com with that!

[flybayer]

Thanks @Lani, good suggestion

[dawnofmidnight]

If no one wants to take this, I can try getting it started. Although I doubt I'd be able to do it all myself.

[flybayer]

@dawnofmidnight cool, and yeah just do as much or as little as you want.

[dawnofmidnight]

Actually, I don't think I'll be able to do this as I've been rather busy lately.

[maybebored]

Happy to take this if it's still open

[beerose]

Still open, go ahead @maybebored!

[maybebored]

I drafted a PR, could use some feedback there before I continue to add more docs. What kind of info is useful?

This also begs the question, could we use this to auto generate a different type of doc in the future? The documentation website serves more like a guide than a full list of the API spec.

[beerose]

I drafted a PR, could use some feedback there before I continue to add more docs. What kind of info is useful?

I think having @params and @returns in TSDoc would be good. And a one-sentence summary of what the function does. In some cases using a @example would also be beneficial. If there's a default value, we should probably also have @defaultValue mentioned in TSDoc. I see you're also adding links to the docs (@see) — great idea!

In general, if a function has TSDoc, it should be super precise so that we won't accidentally cause any confusion for users.

[maybebored]

I drafted a PR, could use some feedback there before I continue to add more docs. What kind of info is useful?

I think having @params and @returns in TSDoc would be good. And a one-sentence summary of what the function does. In some cases using a @example would also be beneficial. If there's a default value, we should probably also have @defaultValue mentioned in TSDoc. I see you're also adding links to the docs (@see) — great idea!

In general, if a function has TSDoc, it should be super precise so that we won't accidentally cause any confusion for users.

That makes sense. @params and @returns would work best for functions. I'm trying to documents Components and Hooks where @example would make a lot of sense. Good feedback!

[maybebored]

I've updated the PR, for a few components. Please help review. Hope this kick starts more parts of the codebase to be documented!

[dmahajan980]

I'd like to pick this up for my first contribution, if it's available!

[beerose]

Go ahead @dmahajan980! There are still many functions without tsdoc comments, so feel free to document at least one.

[kamatheuska]

I would like to contribute as well on this issue, if possible/necessary. Seems like a great first issue!

[beerose]

Go ahead @kamatheuska!