Update JSDoc comments that get shown in editor #2999
Conversation
🦋 Changeset detectedLatest commit: 752d62d The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
github-actions
bot
added
the
pkg: astro
Princesseuh
changed the title
Princesseuh
changed the title
| * [Astro documentation](https://docs.astro.build/en/guides/server-side-rendering/#astroredirect) | ||
| */ | ||
| redirect(path: string): Response; | ||
| /** Utility functions for modifying an Astro component’s slotted children |
There was a problem hiding this comment.
Since writing just Astro.slots is rare, I just copied the documentation and didn't elaborate further outside of a link
I know this technically does not document what Astro.slots really is, but our documentation also doesn't, so I figured we might not want users to use it directly (instead preferring the helper methods)
| @@ -95,12 +175,29 @@ export interface AstroGlobalPartial { | |||
| /** | |||
| * @deprecated since version 0.24. See the {@link https://astro.build/deprecated/resolve upgrade guide} for more details. | |||
| */ | |||
| resolve: (path: string) => string; | |||
| /** @deprecated Use `Astro.glob()` instead. */ | |||
| resolve(path: string): string; | |||
There was a problem hiding this comment.
As far as I know, in an interface there's no functional difference between defining a method using an arrow function or like this.
However, using an arrow function does change JSDoc behavior as we want the JSDoc comment on the function and not the resolve attribute, othewise TypeScript won't show the comment (and not get tags such as @deprecated) when using the method
This is particularly relevant here because Astro.resolve is deprecated and as such, should be striked-through in editors (which it didn't before this change)
There was a problem hiding this comment.
Oh! Very interesting, good to know.
Changes
This updates all of our JSDoc comments on public-facing API in Astro files (so, Astro global, its methods etc) in order to improve the hover info we provide to users in the editor
It is not necessary to document client directives and other Astro-attributes as the language-server provides its own description for those using another mechanism (because those kinda lives in "HTML" land)
Example:
Before
After
I am not the best writer in the world regarding those short snippets so really, suggestions are very much welcome!
Testing
No tests needed
Docs
I guess, this is technically docs itself..