From d1f292199ce309c55c57827a8de0409bd73bb3e8 Mon Sep 17 00:00:00 2001 From: Erika <3019731+Princesseuh@users.noreply.github.com> Date: Thu, 7 Apr 2022 17:08:27 -0400 Subject: [PATCH] Update JSDoc comments that get shown in editor (#2999) --- .changeset/shaggy-pans-buy.md | 5 ++ packages/astro/env.d.ts | 5 +- packages/astro/src/@types/astro.ts | 115 ++++++++++++++++++++++++++--- 3 files changed, 114 insertions(+), 11 deletions(-) create mode 100644 .changeset/shaggy-pans-buy.md diff --git a/.changeset/shaggy-pans-buy.md b/.changeset/shaggy-pans-buy.md new file mode 100644 index 000000000000..742b5e0f7734 --- /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 ebb416dd2681..54f9b17279e5 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; diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts index 76e24a4a0fca..c0764dc00bdd 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; + * --- + *

{id}

+ * ``` + * + * [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; - /** 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 & { + /** + * 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') + * } + * --- + * + * ``` + * + * [Astro documentation](https://docs.astro.build/en/reference/api-reference/#astroslots) + */ render(slotName: string, args?: any[]): Promise; }; } @@ -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; + /** + * 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; glob>(globStr: `${any}.md`): Promise[]>; glob>(globStr: string): Promise; + /** + * 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; }