USWDS - Web components: Improve component docs with custom elements manifest #67
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Improve autogenerated StorybookJS documentation by re-using existing JSDoc comments that follow [custom elements manifest tags](https://custom-elements-manifest.open-wc.org/analyzer/getting-started/#supported-jsdoc)
mejiaj
commented
Sep 5, 2024
Comment on lines
+1
to
+7
| /** | ||
| * Custom elements for component docs generation. | ||
| */ | ||
| import { setCustomElementsManifest } from "@storybook/web-components"; | ||
| import customElements from "../custom-elements.json"; | ||
|
|
||
| setCustomElementsManifest(customElements); |
There was a problem hiding this comment.
Tip
This is how StorybookJS uses the manifest to generate docs.
mejiaj
commented
Sep 5, 2024
| @@ -3,6 +3,7 @@ | |||
| "private": true, | |||
| "version": "1.0.0-alpha", | |||
| "type": "module", | |||
| "customElements": "custom-elements.json", | |||
There was a problem hiding this comment.
Tip
Allows other tools to pickup these hints. Could be useful to developers building with these components.
heymatthenry
approved these changes
Sep 6, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Improve component API documentation by re-using JSDoc comments.
You can see in the screenshot below attributes and CSS custom properties are now documented automatically. ✨
Related issue
Closes #66.
Preview link
Problem statement
Desired state
Component API is automatically documented based on our code comments. This information should be accessible for reuse by other developers too.
Actual state
We have to manually document component API in code and in StorybookJS.
Consequences of remaining in current state
This is time consuming, tedious, and slows down development efforts.
There's also very little benefit to users of these web components because our documentation is internal.
Solution
Added the
custom-elements-manifestdependency so that we can autogenerate the JSON for our component API's. StorybookJS looks for this information to create documentation.Adding it to
package.jsonalso allows other tools to access this information too.web-components/package.json
Line 6 in c13acdc
Source →
Major changes
Followed guidance here to install and setup this tool for StorybookJS.
How to use
Simply add JSDoc comments with this guidance and manifest and docs will automatically be generated.
New NPM scripts
web-components/package.json
Lines 34 to 35 in 2be8e1f
You can manually build or automatically create a new manifest while developing via
npm start.Testing and review
npm installnpm startnpm run manifest:buildandnpm run manifest:watch] without errors.Dependency updates