-
Notifications
You must be signed in to change notification settings - Fork 398
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
docs: adds generated reference #2269
base: main
Are you sure you want to change the base?
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2269 +/- ##
=======================================
Coverage 87.78% 87.78%
=======================================
Files 19 19
Lines 1646 1646
Branches 464 464
=======================================
Hits 1445 1445
Misses 194 194
Partials 7 7 ☔ View full report in Codecov by Sentry. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📚 😭 It's so great to find all of these comments in website format. I'm pretty dang hyped for this!
During browsing I noticed a few strange things without a super clear cause to me. These aren't blockers IMO but it might be nice to at least check out before more review 🙏
🪓 Stricken and deprecated reference
This might ackchyually be caused from JSdoc comments and not the changes here, so feel free to ignore in this PR. I do think it's worth reviewing all of these eventually, but maybe after major changes settle. Anyways, this page me by surprise:
http://localhost:3000/bolt-js/generated-reference/interfaces/Actionable
It makes sense that we include deprecated reference IMO, but I do think this is just a strange case I'm calling out...
🔍 References to libraries
Typing details from other packages and modules are included in reference which at first seemed noisy, but I do think this is useful for completeness (which IMHO is what the ideal reference has).
We might want to consider the Node version we're using for some of this reference though. AFAIK the typings between Node 20 (the current build) and Node 22 can change and are often more verbose or improved, but this might cause conflicts with built-in types:
http://localhost:3000/bolt-js/generated-reference/classes/AppInitializationError#returns
🚂 Sidebar overflows
This seems to be strangeness with Docusaurus, but I find when i CTRL+F characters beyond the shown sidebar, strange wrapping can happen (although this is no blocker at all IMO):
.stylelintrc.json | ||
content/generated-reference |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Super neat that we can generate this just for the final build
!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: Could these lines be indented with 2
spaces 👾
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looking great!
+1 to everything @zimeg mentioned.
Also: could we strip out the JSDoc-specific tags, like @description
? Feel like that's redundant.
Summary
This adds a generated reference. Leaving it "Generated Reference" to compare with the current "Reference" as feedback is gathered. Let me know what you think! Just throwing it up here before I'm off for a bit next week
The generated files are not checked into git because there are hundreds. They'll show up on the site with
npm run start
ornpm run build
though! Grab this branch and run it locally on your machine to view the docs.boltjs-generated-reference.mov
Requirements (place an
x
in each[ ]
)