Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JSDoc and typescript declaration file (*.d.ts) #163

Open
WoonchanCho opened this issue Jan 28, 2021 · 10 comments · May be fixed by #165
Open

JSDoc and typescript declaration file (*.d.ts) #163

WoonchanCho opened this issue Jan 28, 2021 · 10 comments · May be fixed by #165

Comments

@WoonchanCho
Copy link
Contributor

Hi @pieper and other maintainers,
Thank you so much for initiating and maintaining this great project.
I am trying to test this library out as much as I can in our team's projects and enjoy using it now.

This is not a production issue at all but a kind of improvement suggestion.
As you know, the source code itself is not fully documented.
It would be great to have JsDoc comments at the JavaScript source level.

This will help a lot to users who use a modern editor that provides an IntelliSense with the JsDocs comments.
Even more than that, it will also make creating & maintaining the typescript declaration files (*.d.ts) extremely easy.

I will be happy to add the JsDoc comment to all the active JavaScript sources in the project.
For sure, this will be (should be) no harm to the functionalities of the library because this work will only add comments package.json for the two DevDependencies: JsDoc and TypeScript (Typescript will be used only for creating declaration files)

My only concern is that I'm not a native English speaker, there might be some awkward expression used.
If I add those JsDoc comments, can you review them and update if there is anything weird?

Thank you so much.

@hackermd
Copy link
Member

@pieper I have Typescript type declarations for parts of the library, which I would be happy to share/add and which we could build on.

@pieper
Copy link
Collaborator

pieper commented Jan 28, 2021

Hi @WoonchanCho and @hackermd - these sound like great improvements to me. The core code is pretty stable at this point so now would be a good time to put in some more documentation and ts help. I'd be happy to review and edit 👍

@hackermd
Copy link
Member

Great! @WoonchanCho I have type annoations for the sr subpackage. We could then start from there. I will prepare a pull request.

@WoonchanCho
Copy link
Contributor Author

Sounds great! Then I will wait till @hackermd's pull request is merged into the master branch (or a new branch for this work) and begin working after it.

@WoonchanCho
Copy link
Contributor Author

Hi @hackermd, I just wanted to check the status on the type annotation for the sr subpackage. If you are busy for something or need to take more time I might begin to work and you can add on your work on it.
I'm opened to anything so feel free to let me know.

@hackermd
Copy link
Member

hackermd commented Feb 2, 2021

@WoonchanCho I have a type declarations file. It's not yet complete and I have yet tested its distribution via the npm. I will push what I have and then we can discuss outstanding TODO items. OK?

@hackermd hackermd linked a pull request Feb 2, 2021 that will close this issue
@hackermd hackermd linked a pull request Feb 2, 2021 that will close this issue
@kresli
Copy link

kresli commented Aug 22, 2024

any updates on this? TS support would be very much appreciated.

@pieper
Copy link
Collaborator

pieper commented Aug 22, 2024

No, I don't think anyone has had a chance to work on it and @hackermd has moved to a new position. Anyone who wants to pick up the effort is welcome.

@kresli
Copy link

kresli commented Aug 22, 2024

we could generate .d.ts easily by running dts-gen but that would only work if typescripts can infer types automatically. To help typescript we could write JSDOC. That would be much easier then keep .d.ts manually updated. What is your preference? JSDOC + autogenerated .d.ts OR hardcoded .d.ts? Here is an example of autogenerated .d.ts. in current state

image

@pieper
Copy link
Collaborator

pieper commented Aug 22, 2024

I don't really have any experience with ts so I'll defer to others, but anything that simplifies/automates the process would be good. If it did double-duty to help generate API documentation that sounds like a win.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants