docs: document asset utilities #13355
Conversation
🦋 Changeset detectedLatest commit: 49f4c41 The changes in this PR will be included in the next version bump. Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This comment was marked as duplicate.
This comment was marked as duplicate.
Sorry, something went wrong.
Co-authored-by: Junseong Park <[email protected]>
| * Checks if the given URL's port matches the specified port. If no port is provided, it returns true. | ||
| * | ||
| * @param {URL} url - The URL object whose port will be checked. | ||
| * @param {string} [port] - The port to match against the URL's port. Optional. |
There was a problem hiding this comment.
Just wondering whether you already have a precedent for how you show optional parameters and suggesting that you be consistent with that that if it exists.
In docs, for example, I think we tend to "front-load" the optional part, or even if we don't, it's usually lowercase and in parenthesis:
* @param {string} [port] - (optional) The port to match against the URL's port.
Not suggesting you need to change this! Only a reminder that if you do have other optional params already written, it's nice if they're written the same way consistently!
There was a problem hiding this comment.
As per JSDoc, a parameter is optional when is surrounded in square brackets: https://jsdoc.app/tags-param#optional-parameters-and-default-values
In this example, the variable port is optional because it's written [port]. Unfortunately, the IDEs aren't very good at this, and they don't render it as optional
There was a problem hiding this comment.
OK, not opposed to adding Optional. at the end of the text if you think that's a helpful way to display it! Just wanted to see if you already had a convention to follow because it seems like there would be other optional values, too, and it's always great if things are consistent. I leave it totally up to you!
Co-authored-by: Sarah Rainsberger <[email protected]>
4 participants
Changes
This PR documents the asset utilities that we expose to users.
It seems that these aren't properly documented, so I wanted to start from here, and then send a PR to docs to make it official.
Testing
N/A
Docs
FYI, I helped myself with an AI tool, so I would appreciate a second pair of eyes. I already checked what the AI tool wrote before sending the PR.
/cc @withastro/maintainers-docs for feedback!