From 88a75264e70effbe0773f3b393266965ec41ab53 Mon Sep 17 00:00:00 2001
From: Jake Champion <jchampion@fastly.com>
Date: Fri, 9 Dec 2022 12:08:37 +0000
Subject: [PATCH] docs: improve documentation for fastly:env and add full c@e
 example including fiddle

---
 types/fastly:env.d.ts | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/types/fastly:env.d.ts b/types/fastly:env.d.ts
index 06509d8465..5834cee62a 100644
--- a/types/fastly:env.d.ts
+++ b/types/fastly:env.d.ts
@@ -3,9 +3,33 @@ declare module "fastly:env" {
    * Function to get the value for the provided environment variable name.
    *
    * For a list of available environment variables, see the [Fastly Developer Hub for C@E Environment Variables](https://developer.fastly.com/reference/compute/ecp-env/)
+   * 
+   * **Note**: The environment variables can only be retrieved when processing requests, not during build-time initialization.
    *
    * @param name The name of the environment variable
-   * @returns The value of the environment variable
+   * 
+   * @example
+   * <script async defer src="https://fiddle.fastly.dev/embed.js"></script>
+   * In this example we log to stdout the environment variables `FASTLY_HOSTNAME` and `FASTLY_TRACE_ID`.
+   * 
+   * <a href='https://fiddle.fastly.dev/fiddle/276f3cdd/embedded'>View this example on Fastly Fiddle</a>
+   * <noscript>
+   * ```js
+   * /// <reference types="@fastly/js-compute" />
+   * import { env } from "fastly:env";
+   * 
+   * function app(event) {
+   *   console.log("FASTLY_HOSTNAME:", env("FASTLY_HOSTNAME"));
+   *   console.log("FASTLY_TRACE_ID:", env("FASTLY_TRACE_ID"));
+   * 
+   *   return new Response("", {
+   *     status: 200
+   *   });
+   * }
+   * 
+   * addEventListener("fetch", event => event.respondWith(app(event)));
+   * ```
+   * </noscript>
    */
-  export function env(name: string): string;
+  function env(name: string): string;
 }