plot
plot copied to clipboard
observablehq
Add script to inject JSDoc into README.md
This adds a script that will inject the JSDoc into the README.md file for any symbols exported from src/index.js.
Add to the README:
<!-- jsdoc foo -->
<!-- jsdocEnd -->
where foo is anything exported via src/index.js. Note that when using aliases, (e.g. export {basic as transform}), you reference the alias in the html comment. yarn readme:update will get the JSDoc for foo and inject it between those html comments. If injecting multiple JSDocs consecutively, jsdocEnd is only required after the last one. E.g. this will work:
<!-- jsdoc valueof -->
<!-- jsdoc transform -->
<!-- jsdoc column -->
<!-- jsdocEnd -->
Right now, this script will also generate the h4 titles based on the actual parameters found in the code. This is nice, because if you add or rename a parameter, the README will require an update (and will be caught by the github action). That does require, though, that we rename parameters in the code to match what we want to appear in the readme (as I did in for basic in basic.js).
If you both like this approach I will go through and add the annotations for all of the other exported symbols 🙏
I added yarn readme:check to the Node.js CI github action but I can put it into a separate action if preferable. You can see that the first commit in this PR (intentionally) was out of sync and so CI failed: https://github.com/observablehq/plot/runs/7563275291?check_suite_focus=true
Love it! I don't mind marking the parameters by hand if it can make the code a bit lighter. We're not changing parameter names at random, and it will allow more control—like the the brackets ([param]) for optional arguments (although I guess the script could also treat those automagically).
I don't mind marking the parameters by hand if it can make the code a bit lighter. We're not changing parameter names at random, and it will allow more control—like the the brackets ([param]) for optional arguments (although I guess the script could also treat those automagically).
Makes sense. My take was that we will want to rename these parameters anyway, so that editors hints (like signature help) will align with the documentation. And yep, we can detect if parameters are optional
I've added a few comments.
One thing that would be nice to change is to replace https://github.com/observablehq/plot/blob/main/README.md# with # in the produced README.md file, so that it can be read outside of github.
I've added a few comments.
One thing that would be nice to change is to replace
https://github.com/observablehq/plot/blob/main/README.md#with#in the produced README.md file, so that it can be read outside of github.
Good call -- will do!
I don't like the changes in arguments' names that cascade through the documentation (meaning we'll also have to modify links and texts). It is not out of control since there are only a few of them, but we could opt for a more conservative approach of not changing any name. Then it would mean that we need to break the "shadowing" problem. Maybe worth it?
I don't like the changes in arguments' names that cascade through the documentation (meaning we'll also have to modify links and texts). It is not out of control since there are only a few of them, but we could opt for a more conservative approach of not changing any name. Then it would mean that we need to break the "shadowing" problem. Maybe worth it?
Paired with @Fil to make sure to use the original README as the source of truth for argument names