diff options
| -rw-r--r-- | .changeset/shaggy-pans-buy.md | 5 | ||||
| -rw-r--r-- | packages/astro/env.d.ts | 5 | ||||
| -rw-r--r-- | packages/astro/src/@types/astro.ts | 115 |
3 files changed, 114 insertions, 11 deletions
diff --git a/.changeset/shaggy-pans-buy.md b/.changeset/shaggy-pans-buy.md new file mode 100644 index 000000000..742b5e0f7 --- /dev/null +++ b/.changeset/shaggy-pans-buy.md @@ -0,0 +1,5 @@ +--- +'astro': patch +--- + +Update JSDoc comments that get shown to users through editor integration diff --git a/packages/astro/env.d.ts b/packages/astro/env.d.ts index ebb416dd2..54f9b1727 100644 --- a/packages/astro/env.d.ts +++ b/packages/astro/env.d.ts @@ -4,8 +4,9 @@ type Astro = import('astro').AstroGlobal; // We duplicate the description here because editors won't show the JSDoc comment from the imported type (but will for its properties, ex: Astro.request will show the AstroGlobal.request description) /** - * Astro.* available in all components - * Docs: https://docs.astro.build/reference/api-reference/#astro-global + * Astro global available in all contexts in .astro files + * + * [Astro documentation](https://docs.astro.build/reference/api-reference/#astro-global) */ declare const Astro: Readonly<Astro>; diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts index 76e24a4a0..c0764dc00 100644 --- a/packages/astro/src/@types/astro.ts +++ b/packages/astro/src/@types/astro.ts @@ -72,21 +72,101 @@ export interface BuildConfig { } /** - * Astro.* available in all components - * Docs: https://docs.astro.build/reference/api-reference/#astro-global + * Astro global available in all contexts in .astro files + * + * [Astro documentation](https://docs.astro.build/reference/api-reference/#astro-global) */ export interface AstroGlobal extends AstroGlobalPartial { - /** get the current canonical URL */ + /** Canonical URL of the current page. If the [site](https://docs.astro.build/en/reference/configuration-reference/#site) config option is set, its origin will be the origin of this URL. + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astrocanonicalurl) + */ canonicalURL: URL; - /** get page params (dynamic pages only) */ + /** Parameters passed to a dynamic page generated using [getStaticPaths](https://docs.astro.build/en/reference/api-reference/#getstaticpaths) + * + * Example usage: + * ```astro + * --- + * export async function getStaticPaths() { + * return [ + * { params: { id: '1' } }, + * ]; + * } + * + * const { id } = Astro.params; + * --- + * <h1>{id}</h1> + * ``` + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#params) + */ params: Params; - /** set props for this astro component (along with default values) */ + /** List of props passed to this component + * + * A common way to get specific props is through [destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment), ex: + * ```typescript + * const { name } = Astro.props + * ``` + * + * [Astro documentation](https://docs.astro.build/en/core-concepts/astro-components/#component-props) + */ props: Record<string, number | string | any>; - /** get information about this page */ + /** Information about the current request. This is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object + * + * For example, to get a URL object of the current URL, you can use: + * ```typescript + * const url = new URL(Astro.request.url); + * ``` + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astrorequest) + */ request: Request; - /** see if slots are used */ + /** Redirect to another page (**SSR Only**) + * + * Example usage: + * ```typescript + * if(!isLoggedIn) { + * return Astro.redirect('/login'); + * } + * ``` + * + * [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 + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astroslots) + */ slots: Record<string, true | undefined> & { + /** + * Check whether content for this slot name exists + * + * Example usage: + * ```typescript + * if (Astro.slots.has('default')) { + * // Do something... + * } + * ``` + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astroslots) + */ has(slotName: string): boolean; + /** + * Asychronously renders this slot and returns HTML + * + * Example usage: + * ```astro + * --- + * let html: string = ''; + * if (Astro.slots.has('default')) { + * html = await Astro.slots.render('default') + * } + * --- + * <Fragment set:html={html} /> + * ``` + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astroslots) + */ render(slotName: string, args?: any[]): Promise<string>; }; } @@ -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; + /** @deprecated since version 0.26. Use [Astro.glob()](https://docs.astro.build/en/reference/api-reference/#astroglob) instead. */ fetchContent(globStr: string): Promise<any[]>; + /** + * Fetch local files into your static site setup + * + * Example usage: + * ```typescript + * const posts = await Astro.glob('../pages/post/*.md'); + * ``` + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astroglob) + */ glob(globStr: `${any}.astro`): Promise<ComponentInstance[]>; glob<T extends Record<string, any>>(globStr: `${any}.md`): Promise<MarkdownInstance<T>[]>; glob<T extends Record<string, any>>(globStr: string): Promise<T[]>; + /** + * Returns a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object built from the [site](https://docs.astro.build/en/reference/configuration-reference/#site) config option + * + * If `site` is undefined, the URL object will instead be built from `localhost` + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astrosite) + */ site: URL; } |