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

Add scripts to produce documentation using jsdoc #592

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

tahini
Copy link
Contributor

@tahini tahini commented Jul 10, 2024

fixes #591

Add yarn scripts to generate documentation for the evolution-common javascript code.

TODO

  • Document the typescript code instead, so that the types are also documented
  • Document all the evolution packages, not just common
  • Provide a higher level "glue" to document high level concepts that can then link to the jsdoc complete documentation of the packages.

To use this commit, you need to install jsdoc globally on your system with

npm i -g jsdoc

fixes chairemobilite#591

Add yarn scripts to generate documentation for the `evolution-common`
javascript code.

TODO

* Document the typescript code instead, so that the types are also
  documented
* Document all the evolution packages, not just `common`
* Provide a higher level "glue" to document high level concepts that can
  then link to the jsdoc complete documentation of the packages.

To use this commit, you need to install `jsdoc` globally on your system
with

`npm i -g jsdoc`
@tahini
Copy link
Contributor Author

tahini commented Jul 10, 2024

I spent a good 15 minutes on this, no more, there's a lot of improvements to do, but it's promising.

The idea comes from a comment by @greenscientist on #583 to have a high-level idea of what's going on. And since I did try to document the code as much as possible, for extension mechanisms at least, it would be great that this doc can be made available somehow at a high level for others to see without reading the code.

Let me know if you think it,s worth spending a few more hours on this to make it "perfect"

@samuel-duhaime
Copy link
Collaborator

Yes, this is really interesting, I could see myself looking at this when trying to find or understand a helper function for Evolution. This has so much potential to help us document our projects.

@greenscientist
Copy link
Contributor

Yes, that's nice. We'll need to find a way to publish it some where and link it into our static doc.

@greenscientist
Copy link
Contributor

@tahini @samuel-duhaime should we rabase and merge?

@samuel-duhaime
Copy link
Collaborator

Yes, this could be nice. Let's rebase and push this @tahini .

@tahini
Copy link
Contributor Author

tahini commented Dec 17, 2024

See the TODO, it is more than a simple rebase and merge, but if we want it, I'll update this.

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 this pull request may close these issues.

doc: Use jsdoc to document Evolution
3 participants