blitz-js / legacy-framework

MIT License
3 stars 2 forks source link

Add tsdoc comments for Blitz functions inside VSCode #32

Open michaelminhvo opened 3 years ago

michaelminhvo commented 3 years ago

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:

Screen Shot 2021-03-24 at 4 04 35 PM

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

Screen Shot 2021-03-24 at 4 04 19 PM

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

Possible implementation(s)

Using jsdocs

flybayer commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

flybayer commented 3 years ago

Thanks @Lani, good suggestion

dawnofmidnight commented 3 years ago

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 commented 3 years ago

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

dawnofmidnight commented 3 years ago

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

maybebored commented 3 years ago

Happy to take this if it's still open

beerose commented 3 years ago

Still open, go ahead @maybebored!

maybebored commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

beerose commented 3 years ago

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

kamatheuska commented 2 years ago

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

beerose commented 2 years ago

Go ahead @kamatheuska!