@pulumi/pulumi 3.124.1-alpha.xf6bdf03 → 3.125.0-alpha.x584ff1c

package/output.d.ts

@@ -1,7 +1,11 @@
 import { Resource } from "./resource";
 /**
- * [output] takes any Input value and converts it into an Output, deeply unwrapping nested Input
- * values as necessary.
+ * @Internal
+ */
+export declare function getAllResources<T>(op: OutputInstance<T>): Promise<Set<Resource>>;
+/**
+ * {@link output} takes any {@link Input} value and converts it into an
+ * {@link Output}, deeply unwrapping nested {@link Input} values as necessary.
  *
  * The expected way to use this function is like so:
  *
@@ -19,21 +23,25 @@ import { Resource } from "./resource";
 export declare function output<T>(val: Input<T>): Output<Unwrap<T>>;
 export declare function output<T>(val: Input<T> | undefined): Output<Unwrap<T | undefined>>;
 /**
- * [secret] behaves the same as [output] except the returned output is marked as containing sensitive data.
+ * {@link secret} behaves the same as {@link output} except the returned output
+ * is marked as containing sensitive data.
  */
 export declare function secret<T>(val: Input<T>): Output<Unwrap<T>>;
 export declare function secret<T>(val: Input<T> | undefined): Output<Unwrap<T | undefined>>;
 /**
- * [unsecret] behaves the same as [output] except the returned output takes the existing output and unwraps the secret
+ * {@link unsecret} behaves the same as {@link output} except the returned
+ * output takes the existing output and unwraps the secret.
  */
 export declare function unsecret<T>(val: Output<T>): Output<T>;
 /**
- * [isSecret] returns `true` if and only if the provided [Output] is a secret.
+ * {@link isSecret} returns `true` if and only if the provided {@link Output} is
+ * a secret.
  */
 export declare function isSecret<T>(val: Output<T>): Promise<boolean>;
 /**
- * Allows for multiple Output objects to be combined into a single Output object.  The single Output
- * will depend on the union of Resources that the individual dependencies depend on.
+ * Allows for multiple {@link Output} objects to be combined into a single
+ * {@link Output} object.  The single {@link Output} will depend on the union of
+ * {@link Resources} that the individual dependencies depend on.
  *
  * This can be used in the following manner:
  *
@@ -44,8 +52,8 @@ export declare function isSecret<T>(val: Output<T>): Promise<boolean>;
  * var d3: Output<ResultType> = Output.all([d1, d2]).apply(([s, n]) => ...);
  * ```
  *
- * In this example, taking a dependency on d3 means a resource will depend on all the resources of
- * d1 and d2.
+ * In this example, taking a dependency on `d3` means a resource will depend on
+ * all the resources of `d1` and `d2`.
  */
 export declare function all<T>(val: Record<string, Input<T>>): Output<Record<string, Unwrap<T>>>;
 export declare function all<T1, T2, T3, T4, T5, T6, T7, T8>(values: [Input<T1>, Input<T2>, Input<T3>, Input<T4>, Input<T5>, Input<T6>, Input<T7>, Input<T8>]): Output<[Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>, Unwrap<T5>, Unwrap<T6>, Unwrap<T7>, Unwrap<T8>]>;
@@ -57,26 +65,29 @@ export declare function all<T1, T2, T3>(values: [Input<T1>, Input<T2>, Input<T3>
 export declare function all<T1, T2>(values: [Input<T1>, Input<T2>]): Output<[Unwrap<T1>, Unwrap<T2>]>;
 export declare function all<T>(ds: Input<T>[]): Output<Unwrap<T>[]>;
 /**
- * isUnknown returns true if the given value is unknown.
+ * Returns true if the given value is unknown.
  */
 export declare function isUnknown(val: any): boolean;
 /**
- * containsUnknowns returns true if the given value is or contains unknown values.
+ * Returns true if the given value is or contains unknown values.
  */
 export declare function containsUnknowns(value: any): boolean;
 /**
- * [Input] is a property input for a resource.  It may be a promptly available T, a promise for one,
- * or the output from a existing Resource.
+ * {@link Input} is a property input for a resource. It may be a promptly
+ * available `T`, a promise for one, or the {@link Output} from a existing
+ * {@link Resource}.
  */
 export declare type Input<T> = T | Promise<T> | OutputInstance<T>;
 /**
- * [Inputs] is a map of property name to property input, one for each resource property value.
+ * {@link Inputs} is a map of property name to property input, one for each
+ * resource property value.
  */
 export declare type Inputs = Record<string, Input<any>>;
 /**
- * The 'Unwrap' type allows us to express the operation of taking a type, with potentially deeply
- * nested Promises and Outputs and to then get that same type with all the Promises and Outputs
- * replaced with their wrapped type.  Note that this Unwrapping is 'deep'.  So if you had:
+ * The {@link Unwrap} type allows us to express the operation of taking a type,
+ * with potentially deeply nested {@link Promise}s and {@link Output}s and to
+ * then get that same type with all the promises and outputs replaced with their
+ * wrapped type.  Note that this unwrapping is "deep". So if you had:
  *
  *      `type X = { A: Promise<{ B: Output<{ c: Input<boolean> }> }> }`
  *
@@ -84,18 +95,20 @@ export declare type Inputs = Record<string, Input<any>>;
  *
  *      `...    = { A: { B: { C: boolean } } }`
  *
- * Unwrapping sees through Promises, Outputs, Arrays and Objects.
+ * Unwrapping sees through promises, outputs, arrays and objects.
  *
- * Note: due to TypeScript limitations there are some things that cannot be expressed. Specifically,
- * if you had a `Promise<Output<T>>` then the Unwrap type would not be able to undo both of those
- * wraps. In practice that should be ok.  Values in an object graph should not wrap Outputs in
- * Promises.  Instead, any code that needs to work Outputs and also be async should either create
- * the Output with the Promise (which will collapse into just an Output).  Or, it should start with
- * an Output and call [apply] on it, passing in an async function.  This will also collapse and just
- * produce an Output.
+ * Note: due to TypeScript limitations there are some things that cannot be
+ * expressed. Specifically, if you had a `Promise<Output<T>>` then the {@link
+ * Unwrap} type would not be able to undo both of those wraps. In practice that
+ * should be OK. Values in an object graph should not wrap outputs in promises.
+ * Instead, any code that needs to work Outputs and also be async should either
+ * create the output with the promise (which will collapse into just an output).
+ * Or, it should start with an output and call `apply` on it, passing in an
+ * `async` function. This will also collapse and just produce an output.
  *
- * In other words, this should not be used as the shape of an object: `{ a: Promise<Output<...>> }`.
- * It should always either be `{ a: Promise<NonOutput> }` or just `{ a: Output<...> }`.
+ * In other words, this should not be used as the shape of an object: `{ a:
+ * Promise<Output<...>> }`. It should always either be `{ a: Promise<NonOutput>
+ * }` or just `{ a: Output<...> }`.
  */
 export declare type Unwrap<T> = T extends Promise<infer U1> ? UnwrapSimple<U1> : T extends OutputInstance<infer U2> ? UnwrapSimple<U2> : UnwrapSimple<T>;
 declare type primitive = Function | string | number | boolean | undefined | null;
@@ -108,35 +121,40 @@ export declare type UnwrappedObject<T> = {
     [P in keyof T]: Unwrap<T[P]>;
 };
 /**
- * Instance side of the [Output<T>] type.  Exposes the deployment-time and run-time mechanisms
- * for working with the underlying value of an [Output<T>].
+ * Instance side of the {@link Output} type. Exposes the deployment-time and
+ * run-time mechanisms for working with the underlying value of an {@link Output}.
  */
 export interface OutputInstance<T> {
     /**
-     * Transforms the data of the output with the provided func.  The result remains a
-     * Output so that dependent resources can be properly tracked.
+     * Transforms the data of the output with the provided `func`. The result
+     * remains an {@link Output} so that dependent resources can be properly
+     * tracked.
      *
-     * 'func' is not allowed to make resources.
+     * `func` is not allowed to make resources.
      *
-     * 'func' can return other Outputs.  This can be handy if you have a Output<SomeVal>
-     * and you want to get a transitive dependency of it.  i.e.
+     * `func` can return other {@link Output}s. This can be handy if you have an
+     * `Output<SomeVal>` and you want to get a transitive dependency of it,
+     * i.e.
      *
      * ```ts
      * var d1: Output<SomeVal>;
      * var d2 = d1.apply(v => v.x.y.OtherOutput); // getting an output off of 'v'.
      * ```
      *
-     * In this example, taking a dependency on d2 means a resource will depend on all the resources
-     * of d1.  It will *also* depend on the resources of v.x.y.OtherDep.
+     * In this example, taking a dependency on `d2` means a resource will depend
+     * on all the resources of `d1`.  It will *also* depend on the resources of
+     * `v.x.y.OtherDep`.
      *
-     * Importantly, the Resources that d2 feels like it will depend on are the same resources as d1.
-     * If you need have multiple Outputs and a single Output is needed that combines both
-     * set of resources, then 'pulumi.all' should be used instead.
+     * Importantly, the resources that `d2` feels like it will depend on are the
+     * same resources as `d1`. If you need have multiple outputs and a single
+     * output is needed that combines both set of resources, then `pulumi.all`
+     * should be used instead.
      *
-     * This function will be called execution of a 'pulumi up' or 'pulumi preview' request, but it
-     * will ont run when the values of the output are unknown. It is not
-     * available for functions that end up executing in the cloud during runtime.  To get the value
-     * of the Output during cloud runtime execution, use `get()`.
+     * This function will be called during the execution of a `pulumi up` or
+     * `pulumi preview` operation, but it will not run when the values of the
+     * output are unknown. It is not available for functions that end up
+     * executing in the cloud during runtime. To get the value of the Output
+     * during cloud runtime execution, use `get()`.
      */
     apply<U>(func: (t: T) => Promise<U>): Output<U>;
     apply<U>(func: (t: T) => OutputInstance<U>): Output<U>;
@@ -144,17 +162,18 @@ export interface OutputInstance<T> {
     /**
      * Retrieves the underlying value of this dependency.
      *
-     * This function is only callable in code that runs in the cloud post-deployment.  At this
-     * point all Output values will be known and can be safely retrieved. During pulumi deployment
-     * or preview execution this must not be called (and will throw).  This is because doing so
-     * would allow Output values to flow into Resources while losing the data that would allow
-     * the dependency graph to be changed.
+     * This function is only callable in code that runs in the cloud
+     * post-deployment. At this point all {@link Output} values will be known
+     * and can be safely retrieved. During Pulumi deployment or preview
+     * execution this must not be called (and will throw). This is because doing
+     * so would allow output values to flow into resources while losing the data
+     * that would allow the dependency graph to be changed.
      */
     get(): T;
 }
 /**
- * Static side of the [Output<T>] type.  Can be used to [create] Outputs as well as test
- * arbitrary values to see if they are [Output]s.
+ * Static side of the {@link Output} type. Can be used to create outputs as well
+ * as test arbitrary values to see if they are {@link Output}s.
  */
 export interface OutputConstructor {
     create<T>(val: Input<T>): Output<Unwrap<T>>;
@@ -162,30 +181,34 @@ export interface OutputConstructor {
     isInstance<T>(obj: any): obj is Output<T>;
 }
 /**
- * [Output] helps encode the relationship between Resources in a Pulumi application. Specifically an
- * [Output] holds onto a piece of Data and the Resource it was generated from. An [Output] value can
- * then be provided when constructing new Resources, allowing that new Resource to know both the
- * value as well as the Resource the value came from.  This allows for a precise 'Resource
- * dependency graph' to be created, which properly tracks the relationship between resources.
- *
- * An [Output] is used in a Pulumi program differently depending on if the application is executing
- * at 'deployment time' (i.e. when actually running the 'pulumi' executable), or at 'run time' (i.e.
- * a piece of code running in some Cloud).
- *
- * At 'deployment time', the correct way to work with the underlying value is to call
- * [Output.apply(func)].  This allows the value to be accessed and manipulated, while still
- * resulting in an [Output] that is keeping track of [Resource]s appropriately.  At deployment time
- * the underlying value may or may not exist (for example, if a preview is being performed).  In
- * this case, the 'func' callback will not be executed, and calling [.apply] will immediately return
- * an [Output] that points to the [undefined] value.  During a normal [update] though, the 'func'
- * callbacks should always be executed.
- *
- * At 'run time', the correct way to work with the underlying value is to simply call [Output.get]
- * which will be promptly return the entire value.  This will be a simple JavaScript object that can
- * be manipulated as necessary.
- *
- * To ease with using [Output]s at 'deployment time', pulumi will 'lift' simple data properties of
- * an underlying value to the [Output] itself.  For example:
+ * {@link Output} helps encode the relationship between {@link Resource}s in a
+ * Pulumi application. Specifically, an {@link Output} holds onto a piece of
+ * data and the resource it was generated from. An output value can then be
+ * provided when constructing new resources, allowing that new resource to know
+ * both the value as well as the resource the value came from.  This allows for
+ * a precise resource dependency graph to be created, which properly tracks the
+ * relationship between resources.
+ *
+ * An output is used in a Pulumi program differently depending on if the
+ * application is executing at "deployment time" (i.e. when actually running the
+ * `pulumi` executable), or at "run time" (i.e. a piece of code running in some
+ * cloud).
+ *
+ * At "deployment time", the correct way to work with the underlying value is to
+ * call {@link Output.apply}. This allows the value to be accessed and
+ * manipulated, while still resulting in an output that is keeping track of
+ * {@link Resource}s appropriately. At deployment time the underlying value may
+ * or may not exist (for example, if a preview is being performed).  In this
+ * case, the `func` callback will not be executed, and calling `.apply` will
+ * immediately return an output that points to the `undefined` value. During a
+ * normal update though, the `func` callbacks should always be executed.
+ *
+ * At "run time", the correct way to work with the underlying value is to simply
+ * call {@link Output.get} which will be promptly return the entire value.  This
+ * will be a simple JavaScript object that can be manipulated as necessary.
+ *
+ * To ease with using outputs at deployment time, Pulumi will "lift" simple data
+ * properties of an underlying value to the output itself.  For example:
  *
  * ```ts
  *      const o: Output<{ name: string, age: number, orders: Order[] }> = ...;
@@ -206,9 +229,10 @@ export interface OutputConstructor {
 export declare type Output<T> = OutputInstance<T> & Lifted<T>;
 export declare const Output: OutputConstructor;
 /**
- * The [Lifted] type allows us to express the operation of taking a type, with potentially deeply
- * nested objects and arrays and to then get a type with the same properties, except whose property
- * types are now [Output]s of the original property type.
+ * The {@link Lifted} type allows us to express the operation of taking a type,
+ * with potentially deeply nested objects and arrays and to then get a type with
+ * the same properties, except whose property types are now {@link Output}s of the
+ * original property type.
  *
  * For example:
  *
@@ -219,12 +243,13 @@ export declare const Output: OutputConstructor;
  *
  *      `...    = { A: Output<string>, B: Output<{ C: Output<boolean> }> }`
  *
- * [Lifted] is somewhat the opposite of [Unwrap].  It's primary purpose is to allow an instance of
- * [Output<SomeType>] to provide simple access to the properties of [SomeType] directly on the instance
- * itself (instead of haveing to use [.apply]).
+ * {@link Lifted} is somewhat the opposite of {@link Unwrap}. Its primary
+ * purpose is to allow an instance of `Output<SomeType>` to provide simple
+ * access to the properties of `SomeType` directly on the instance itself
+ * (instead of haveing to use {@link Output.apply}).
  *
- * This lifting only happens through simple pojo objects and arrays.  Functions, for example, are not
- * lifted.  So you cannot do:
+ * This lifting only happens through simple objects and arrays. Functions, for
+ * example, are not lifted. So you cannot do:
  *
  * ```ts
  *      const o: Output<string> = ...;
@@ -254,9 +279,10 @@ export declare type LiftedArray<T> = {
     readonly [n: number]: Output<T>;
 };
 /**
- * [concat] takes a sequence of [Inputs], stringifies each, and concatenates all values into one
- * final string.  Individual inputs can be any sort of [Input] value.  i.e. they can be [Promise]s,
- * [Output]s, or just plain JavaScript values.  This can be used like so:
+ * {@link concat} takes a sequence of {@link Input}s, stringifies each one, and
+ * concatenates all values into one final string.  Individual inputs can be any
+ * sort of input value: they can be promises, outputs, or just plain JavaScript
+ * values. Use this function like so:
  *
  * ```ts
  *      // 'server' and 'loadBalancer' are both resources that expose [Output] properties.
@@ -266,24 +292,26 @@ export declare type LiftedArray<T> = {
  */
 export declare function concat(...params: Input<any>[]): Output<string>;
 /**
- * [interpolate] is similar to [concat] but is designed to be used as a tagged template expression.
- * i.e.:
+ * {@link interpolate} is similar to {@link concat} but is designed to be used
+ * as a tagged template expression, e.g.:
  *
  * ```ts
  *      // 'server' and 'loadBalancer' are both resources that expose [Output] properties.
  *      let val: Output<string> = pulumi.interpolate `http://${server.hostname}:${loadBalancer.port}`
  * ```
  *
- * As with [concat] the 'placeholders' between `${}` can be any Inputs.  i.e. they can be
- * [Promise]s, [Output]s, or just plain JavaScript values.
+ * As with {@link concat}, the placeholders between `${}` can be any
+ * {@link Input}s: promises, outputs, or just plain JavaScript values.
  */
 export declare function interpolate(literals: TemplateStringsArray, ...placeholders: Input<any>[]): Output<string>;
 /**
- * [jsonStringify] Uses JSON.stringify to serialize the given Input value into a JSON string.
+ * {@link jsonStringify} uses {@link JSON.stringify} to serialize the given
+ * {@link Input} value into a JSON string.
  */
 export declare function jsonStringify(obj: Input<any>, replacer?: (this: any, key: string, value: any) => any | (number | string)[], space?: string | number): Output<string>;
 /**
- * [jsonParse] Uses JSON.parse to deserialize the given Input JSON string into a value.
+ * {@link jsonParse} Uses {@link JSON.parse} to deserialize the given {@link
+ * Input} JSON string into a value.
  */
 export declare function jsonParse(text: Input<string>, reviver?: (this: any, key: string, value: any) => any): Output<any>;
 export {};

package/output.js

@@ -33,19 +33,24 @@ const resource_1 = require("./resource");
 const utils = __importStar(require("./utils"));
 /* eslint-disable no-shadow, @typescript-eslint/no-shadow */
 /**
- * Output helps encode the relationship between Resources in a Pulumi application. Specifically an
- * Output holds onto a piece of Data and the Resource it was generated from. An Output value can
- * then be provided when constructing new Resources, allowing that new Resource to know both the
- * value as well as the Resource the value came from.  This allows for a precise 'Resource
- * dependency graph' to be created, which properly tracks the relationship between resources.
+ * {@link Output} helps encode the relationship between {@link Resource}s in a
+ * Pulumi application. Specifically, an {@link Output} holds onto a piece of
+ * data and the resource it was generated from. An output value can then be
+ * provided when constructing new resources, allowing that new resource to know
+ * both the value as well as the resource the value came from.  This allows for
+ * a precise resource dependency graph to be created, which properly tracks the
+ * relationship between resources.
  */
 class OutputImpl {
-    /** @internal */
+    /**
+     * @internal
+     */
     constructor(resources, promise, isKnown, isSecret, allResources) {
         /**
          * A private field to help with RTTI that works in SxS scenarios.
          *
          * This is internal instead of being truly private, to support mixins and our serialization model.
+         *
          * @internal
          */
         // eslint-disable-next-line @typescript-eslint/naming-convention,no-underscore-dangle,id-blacklist,id-match
@@ -165,13 +170,16 @@ See https://www.pulumi.com/docs/concepts/inputs-outputs for more details.`;
         return output(val);
     }
     /**
-     * Returns true if the given object is an instance of Output<T>.  This is designed to work even when
-     * multiple copies of the Pulumi SDK have been loaded into the same process.
+     * Returns true if the given object is an {@link Output}. This is designed
+     * to work even when multiple copies of the Pulumi SDK have been loaded into
+     * the same process.
      */
     static isInstance(obj) {
         return utils.isInstance(obj, "__pulumiOutput");
     }
-    /** @internal */
+    /**
+     * @internal
+     */
     static getPromisedValue(promise, withUnknowns) {
         return __awaiter(this, void 0, void 0, function* () {
             // If the caller did not explicitly ask to see unknown values and val contains unknowns, return undefined. This
@@ -203,7 +211,9 @@ To manipulate the value of this Output, use '.apply' instead.`);
         return result;
     }
 }
-/** @internal */
+/**
+ * @Internal
+ */
 function getAllResources(op) {
     return op.allResources instanceof Function ? op.allResources() : Promise.resolve(op.resources());
 }
@@ -270,11 +280,13 @@ function applyHelperAsync(allResources, value, isKnown, isSecret, func, runWithU
     });
 }
 /**
- * Returns a promise denoting if the output is a secret or not. This is not the same as just calling `.isSecret`
- * because in cases where the output does not have a `isSecret` property and it is a Proxy, we need to ignore
- * the isSecret member that the proxy reports back.
+ * Returns a promise denoting if the output is a secret or not. This is not the
+ * same as just calling `.isSecret` because in cases where the output does not
+ * have a `isSecret` property and it is a Proxy, we need to ignore the `isSecret`
+ * member that the proxy reports back.
  *
- * This calls the public implementation so that we only make any calculations in a single place.
+ * This calls the public implementation so that we only make any calculations in
+ * a single place.
  *
  * @internal
  */
@@ -283,20 +295,24 @@ function isSecretOutput(o) {
 }
 exports.isSecretOutput = isSecretOutput;
 /**
- * Helper function for `output`.  This function trivially recurses through an object, copying it,
- * while also lifting any inner Outputs (with all their respective state) to a top-level Output at
- * the end.  If there are no inner outputs, this will not affect the data (except by producing a new
- * copy of it).
+ * Helper function for {@link output}. This function trivially recurses through
+ * an object, copying it, while also lifting any inner {@link Outputs} (with all
+ * their respective state) to a top-level output at the end. If there are no
+ * inner outputs, this will not affect the data (except by producing a new copy
+ * of it).
  *
  * Importantly:
  *
- *  1. Resources encountered while recursing are not touched.  This helps ensure they stay Resources
- *     (with an appropriate prototype chain).
+ *  1. Resources encountered while recursing are not touched.  This helps ensure
+ *     they stay Resources (with an appropriate prototype chain).
+ *
  *  2. Primitive values (string, number, etc.) are returned as is.
- *  3. Arrays and Record are recursed into.  An Array<...> that contains any Outputs wil become an
- *     Output<Array<Unwrapped>>.  A Record<string, ...> that contains any Output values will be an
- *     Output<Record<string, Unwrap<...>>.  In both cases of recursion, the outer Output's
- *     known/secret/resources will be computed from the nested Outputs.
+ *
+ *  3. Arrays and records are recursed into. An `Array<...>` that contains any
+ *     `Outputs` wil become an `Output<Array<Unwrapped>>`. A `Record<string, ...>`
+ *     that contains any output values will be an `Output<Record<string Unwrap<...>>`.
+ *     In both cases of recursion, the outer output's known/secret/resources
+ *     will be computed from the nested Outputs.
  */
 function outputRec(val) {
     if (val === null || typeof val !== "object") {
@@ -394,14 +410,16 @@ function secret(val) {
 }
 exports.secret = secret;
 /**
- * [unsecret] behaves the same as [output] except the returned output takes the existing output and unwraps the secret
+ * {@link unsecret} behaves the same as {@link output} except the returned
+ * output takes the existing output and unwraps the secret.
  */
 function unsecret(val) {
     return new exports.Output(val.resources(), val.promise(/*withUnknowns*/ true), val.isKnown, Promise.resolve(false), val.allResources());
 }
 exports.unsecret = unsecret;
 /**
- * [isSecret] returns `true` if and only if the provided [Output] is a secret.
+ * {@link isSecret} returns `true` if and only if the provided {@link Output} is
+ * a secret.
  */
 function isSecret(val) {
     return exports.Output.isInstance(val.isSecret) ? Promise.resolve(false) : val.isSecret;
@@ -471,12 +489,15 @@ function getResourcesAndDetails(allValues) {
     return [syncResources, isKnown, isSecret, allResources];
 }
 /**
- * Unknown represents a value that is unknown. These values correspond to unknown property values received from the
- * Pulumi engine as part of the result of a resource registration (see runtime/rpc.ts). User code is not typically
- * exposed to these values: any Output<> that contains an Unknown will itself be unknown, so any user callbacks
- * passed to `apply` will not be run. Internal callers of `apply` can request that they are run even with unknown
- * values; the output proxy takes advantage of this to allow proxied property accesses to return known values even
- * if other properties of the containing object are unknown.
+ * Unknown represents a value that is unknown. These values correspond to
+ * unknown property values received from the Pulumi engine as part of the result
+ * of a resource registration (see `runtime/rpc.ts`). User code is not typically
+ * exposed to these values: any {@link Output} that contains an {@link Unknown}
+ * will itself be unknown, so any user callbacks passed to `apply` will not be
+ * run. Internal callers of `apply` can request that they are run even with
+ * unknown values; the output proxy takes advantage of this to allow proxied
+ * property accesses to return known values even if other properties of the
+ * containing object are unknown.
  */
 class Unknown {
     constructor() {
@@ -484,33 +505,36 @@ class Unknown {
          * A private field to help with RTTI that works in SxS scenarios.
          *
          * This is internal instead of being truly private, to support mixins and our serialization model.
+         *
          * @internal
          */
         // eslint-disable-next-line @typescript-eslint/naming-convention,no-underscore-dangle,id-blacklist,id-match
         this.__pulumiUnknown = true;
     }
     /**
-     * Returns true if the given object is an instance of Unknown. This is designed to work even when
-     * multiple copies of the Pulumi SDK have been loaded into the same process.
+     * Returns true if the given object is an {@link Unknown}. This is designed
+     * to work even when multiple copies of the Pulumi SDK have been loaded into
+     * the same process.
      */
     static isInstance(obj) {
         return utils.isInstance(obj, "__pulumiUnknown");
     }
 }
 /**
- * unknown is the singleton unknown value.
+ * {@link unknown} is the singleton {@link Unknown} value.
+ *
  * @internal
  */
 exports.unknown = new Unknown();
 /**
- * isUnknown returns true if the given value is unknown.
+ * Returns true if the given value is unknown.
  */
 function isUnknown(val) {
     return Unknown.isInstance(val);
 }
 exports.isUnknown = isUnknown;
 /**
- * containsUnknowns returns true if the given value is or contains unknown values.
+ * Returns true if the given value is or contains unknown values.
  */
 function containsUnknowns(value) {
     return impl(value, new Set());
@@ -537,9 +561,10 @@ exports.containsUnknowns = containsUnknowns;
 // eslint-disable-next-line @typescript-eslint/naming-convention,@typescript-eslint/no-redeclare,no-underscore-dangle,id-blacklist,id-match
 exports.Output = OutputImpl;
 /**
- * [concat] takes a sequence of [Inputs], stringifies each, and concatenates all values into one
- * final string.  Individual inputs can be any sort of [Input] value.  i.e. they can be [Promise]s,
- * [Output]s, or just plain JavaScript values.  This can be used like so:
+ * {@link concat} takes a sequence of {@link Input}s, stringifies each one, and
+ * concatenates all values into one final string.  Individual inputs can be any
+ * sort of input value: they can be promises, outputs, or just plain JavaScript
+ * values. Use this function like so:
  *
  * ```ts
  *      // 'server' and 'loadBalancer' are both resources that expose [Output] properties.
@@ -552,16 +577,16 @@ function concat(...params) {
 }
 exports.concat = concat;
 /**
- * [interpolate] is similar to [concat] but is designed to be used as a tagged template expression.
- * i.e.:
+ * {@link interpolate} is similar to {@link concat} but is designed to be used
+ * as a tagged template expression, e.g.:
  *
  * ```ts
  *      // 'server' and 'loadBalancer' are both resources that expose [Output] properties.
  *      let val: Output<string> = pulumi.interpolate `http://${server.hostname}:${loadBalancer.port}`
  * ```
  *
- * As with [concat] the 'placeholders' between `${}` can be any Inputs.  i.e. they can be
- * [Promise]s, [Output]s, or just plain JavaScript values.
+ * As with {@link concat}, the placeholders between `${}` can be any
+ * {@link Input}s: promises, outputs, or just plain JavaScript values.
  */
 function interpolate(literals, ...placeholders) {
     return output(placeholders).apply((unwrapped) => {
@@ -578,7 +603,8 @@ function interpolate(literals, ...placeholders) {
 }
 exports.interpolate = interpolate;
 /**
- * [jsonStringify] Uses JSON.stringify to serialize the given Input value into a JSON string.
+ * {@link jsonStringify} uses {@link JSON.stringify} to serialize the given
+ * {@link Input} value into a JSON string.
  */
 function jsonStringify(obj, replacer, space) {
     return output(obj).apply((o) => {
@@ -587,7 +613,8 @@ function jsonStringify(obj, replacer, space) {
 }
 exports.jsonStringify = jsonStringify;
 /**
- * [jsonParse] Uses JSON.parse to deserialize the given Input JSON string into a value.
+ * {@link jsonParse} Uses {@link JSON.parse} to deserialize the given {@link
+ * Input} JSON string into a value.
  */
 function jsonParse(text, reviver) {
     return output(text).apply((t) => {