@typespec/compiler 1.18.0-dev.4 → 1.18.0-dev.5

package/dist/src/lib/decorators.d.ts

@@ -9,9 +9,10 @@ export * from "./service.js";
 export * from "./visibility.js";
 export type { ExampleOptions };
 export declare const namespace = "TypeSpec";
+/** Gets the summary stored on this type, or `undefined` if none is set. */
 declare const getSummary: (program: Program, type: Type) => string | undefined;
 /**
- * @summary attaches a documentation string. It is typically used to give a short, single-line
+ * `@summary` attaches a documentation string. It is typically used to give a short, single-line
  * description, and can be used in combination with or instead of @doc.
  *
  * The first argument to @summary is a string, which may contain template parameters, enclosed in braces,
@@ -37,6 +38,7 @@ export declare const $doc: DocDecorator;
  * @returns Documentation value
  */
 export declare function getDoc(program: Program, target: Type): string | undefined;
+/** Attaches documentation describing an operation's successful return types, separately from its errors. */
 export declare const $returnsDoc: ReturnsDocDecorator;
 /**
  * Get the documentation information for the return success types of an operation. In most cases you probably just want to use {@link getReturnsDoc}
@@ -52,6 +54,7 @@ export declare function getReturnsDocData(program: Program, target: Operation):
  * @returns Documentation value
  */
 export declare function getReturnsDoc(program: Program, target: Operation): string | undefined;
+/** Attaches documentation describing an operation's error return types, separately from its successful results. */
 export declare const $errorsDoc: ErrorsDocDecorator;
 /**
  * Get the documentation information for the return errors types of an operation. In most cases you probably just want to use {@link getErrorsDoc}
@@ -67,9 +70,13 @@ export declare function getErrorsDocData(program: Program, target: Operation): D
  * @returns Documentation value
  */
 export declare function getErrorsDoc(program: Program, target: Operation): string | undefined;
+/** Logs an optional nonempty label followed by the target type object, to a depth of three, for debugging. */
 export declare const $inspectType: InspectTypeDecorator;
+/** Logs an optional nonempty label followed by the target's formatted TypeSpec name for debugging. */
 export declare const $inspectTypeName: InspectTypeNameDecorator;
+/** Tests whether the target is a scalar assignable to the standard `string` type, including derived scalars. */
 export declare function isStringType(program: Program, target: Type): target is Scalar;
+/** Tests whether the target is a scalar assignable to the standard `numeric` type, including derived scalars. */
 export declare function isNumericType(program: Program, target: Type): target is Scalar;
 export declare function isDateTimeType(program: Program, target: Type): target is Scalar;
 /**
@@ -114,6 +121,7 @@ export declare function setMediaTypeHint(program: Program, target: MediaTypeHint
  * @returns the default media type hint for the target, if any
  */
 export declare function getMediaTypeHint(program: Program, target: Type): string | undefined;
+/** Gets the format hint stored on this type, or `undefined` if none is set; does not search base types. */
 declare const getFormat: (program: Program, type: Type) => string | undefined;
 /**
  * `@format` - specify the data format hint for a string type
@@ -131,10 +139,14 @@ declare const getFormat: (program: Program, type: Type) => string | undefined;
 export declare const $format: FormatDecorator;
 export { getFormat };
 declare const getPatternData: (program: Program, type: Type) => PatternData | undefined;
+/** A string validation pattern and optional human-readable explanation supplied by `@pattern`. */
 export interface PatternData {
+    /** Regular expression source text, without enclosing slashes or flags. */
     readonly pattern: string;
+    /** Optional explanation emitters can show when a value does not match the pattern. */
     readonly validationMessage?: string;
 }
+/** Records a string validation pattern and optional failure message, reporting invalid regular expressions. */
 export declare const $pattern: PatternDecorator;
 /**
  * Gets the pattern regular expression associated with a given type, if one has been set.
@@ -156,14 +168,23 @@ export {
  * @returns the pattern data, if any was set
  */
 getPatternData, };
+/** Sets an inclusive minimum string length, rejecting a bound greater than the target's maximum length. */
 export declare const $minLength: MinLengthDecorator;
+/** Sets an inclusive maximum string length, rejecting a bound less than the target's minimum length. */
 export declare const $maxLength: MaxLengthDecorator;
+/** Sets an inclusive minimum array item count, rejecting a bound greater than the target's maximum count. */
 export declare const $minItems: MinItemsDecorator;
+/** Sets an inclusive maximum array item count, rejecting a bound less than the target's minimum count. */
 export declare const $maxItems: MaxItemsDecorator;
+/** Sets an inclusive lower bound for a numeric or date/time scalar or property, validating assignability. */
 export declare const $minValue: MinValueDecorator;
+/** Sets an inclusive upper bound for a numeric or date/time scalar or property, validating assignability. */
 export declare const $maxValue: MaxValueDecorator;
+/** Sets an exclusive lower bound for a numeric or date/time scalar or property, validating assignability. */
 export declare const $minValueExclusive: MinValueExclusiveDecorator;
+/** Sets an exclusive upper bound for a numeric or date/time scalar or property, validating assignability. */
 export declare const $maxValueExclusive: MaxValueExclusiveDecorator;
+/** Tests whether this type is marked with `@secret`; does not search base types. */
 declare const isSecret: (program: Program, type: Type) => boolean;
 /**
  * Mark a value as a secret value that should be treated carefully to avoid exposure
@@ -172,9 +193,13 @@ declare const isSecret: (program: Program, type: Type) => boolean;
  */
 export declare const $secret: SecretDecorator;
 export { isSecret };
+/** Standard date/time encoding names accepted by `@encode`, including string formats and Unix seconds. */
 export type DateTimeKnownEncoding = "rfc3339" | "rfc7231" | "unixTimestamp";
+/** Standard duration encoding names for ISO 8601 text or numeric seconds and milliseconds. */
 export type DurationKnownEncoding = "ISO8601" | "seconds" | "milliseconds";
+/** Standard encodings for representing bytes as Base64 or URL-safe Base64 text. */
 export type BytesKnownEncoding = "base64" | "base64url";
+/** Serialization instructions stored by `@encode`, pairing an encoding name with its wire scalar type. */
 export interface EncodeData {
     /**
      * Known encoding key.
@@ -183,19 +208,50 @@ export interface EncodeData {
      * For boolean this means using `true` or `false`.
      */
     encoding?: DateTimeKnownEncoding | DurationKnownEncoding | BytesKnownEncoding | string;
+    /** Scalar used for the encoded representation; defaults to `string` when `@encode` omits it. */
     type: Scalar;
 }
+/** Gets encoding instructions stored on this scalar or property, or `undefined`; does not search base scalars. */
 declare const getEncode: (program: Program, type: ModelProperty | Scalar) => EncodeData | undefined;
+/**
+ * Records how a scalar or property is serialized, validating known encodings against the target and wire types.
+ * Named encodings default to a `string` representation; passing the `string` scalar encodes numeric or boolean values as text.
+ */
 export declare const $encode: EncodeDecorator;
 export { getEncode };
+/** Mutates every property in the target model's own property map to be optional; does not walk base models. */
 export declare const $withOptionalProperties: WithOptionalPropertiesDecorator;
+/**
+ * Removes named properties from the target model in place, without walking base models.
+ * Names come from a string literal or the string-literal variants of a union; other variants are ignored.
+ */
 export declare const $withoutOmittedProperties: WithoutOmittedPropertiesDecorator;
+/**
+ * Removes all properties except the named ones from the target model in place, without walking base models.
+ * Names come from a string literal or the string-literal variants of a union; other variants are ignored.
+ */
 export declare const $withPickedProperties: WithPickedPropertiesDecorator;
+/** Deletes default values from the target model's own properties in place; does not walk base models. */
 export declare const $withoutDefaultValues: WithoutDefaultValuesDecorator;
+/** Appends a tag to an operation, interface, or namespace; multiple tags and duplicate strings are retained. */
 export declare const $tag: TagDecorator;
+/**
+ * Gets only the tags stored directly on the target, or an empty array if none are set.
+ * The stored array is returned without copying; use {@link getAllTags} to include containing scopes.
+ */
 export declare function getTags(program: Program, target: Type): string[];
+/**
+ * Collects unique tags from the target and its enclosing interface and namespaces.
+ * Tags are collected from inner to outer scopes and the deduplicated sequence is reversed before returning.
+ * Returns a new array, or `undefined` if no scope has tags.
+ */
 export declare function getAllTags(program: Program, target: Namespace | Interface | Operation): string[] | undefined;
+/** Gets the friendly name stored on this type, or `undefined`; does not synthesize a name or search base types. */
 declare const getFriendlyName: (program: Program, type: Type) => string | undefined;
+/**
+ * Stores an emitter-facing name without changing the type's TypeSpec name.
+ * When a source object is supplied, its properties replace `{property}` placeholders in the name.
+ */
 export declare const $friendlyName: FriendlyNameDecorator;
 export { getFriendlyName };
 /**
@@ -235,20 +291,46 @@ getOverloadedOperation,
  * Get all operations that are marked as overloads of the given operation
  * @param program Program
  * @param operation Operation
- * @returns An array of operations that overload the given operation.
+ * @returns The stored array of overloads, or `undefined` if none have been registered.
  */
 getOverloads, };
+/**
+ * Configures and validates a discriminated union.
+ * Defaults to an object envelope with discriminator property `kind` and value property `value`.
+ */
 export declare const discriminatedDecorator: DiscriminatedDecorator;
+/** Records the property used to distinguish a model's derived variants during serialization. */
 export declare const $discriminator: DiscriminatorDecorator;
+/** An example attached to a data type, retaining the TypeSpec value and optional display metadata. */
 export interface Example extends ExampleOptions {
+    /** Original TypeSpec value, not serialized JSON; use {@link serializeValueAsJson} to convert it. */
     readonly value: Value;
 }
+/** Example inputs and corresponding result attached to an operation, with optional display metadata. */
 export interface OpExample extends ExampleOptions {
+    /** Value assignable to the operation's parameter model, or absent for a result-only example. */
     readonly parameters?: Value;
+    /** Value assignable to the operation's return type, or absent for a parameter-only example. */
     readonly returnType?: Value;
 }
+/**
+ * Appends an example and optional display metadata to the target after checking value assignability.
+ * Reads the original TypeSpec value from the decorator application rather than the marshalled JS argument.
+ */
 export declare const $example: ExampleDecorator;
+/**
+ * Gets examples stored on the target in registration order, or an empty array.
+ * Returns the stored collection as readonly without copying; values remain TypeSpec values, not JSON.
+ */
 export declare function getExamples(program: Program, target: Model | Scalar | Enum | Union | ModelProperty): readonly Example[];
+/**
+ * Appends example parameter and result values with optional display metadata, checking each supplied value's assignability.
+ * Reads original TypeSpec values from the decorator application rather than the marshalled JS argument.
+ */
 export declare const $opExample: OpExampleDecorator;
+/**
+ * Gets operation examples in registration order, or an empty array if none are set.
+ * Returns the stored array without copying; parameter and result values have not been serialized.
+ */
 export declare function getOpExamples(program: Program, target: Operation): OpExample[];
 //# sourceMappingURL=decorators.d.ts.map

package/dist/src/lib/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../../src/lib/decorators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../../src/lib/decorators.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/decorators.js

@@ -20,9 +20,10 @@ export { getPagingOperation, isList } from "./paging.js";
 export * from "./service.js";
 export * from "./visibility.js";
 export const namespace = "TypeSpec";
+/** Gets the summary stored on this type, or `undefined` if none is set. */
 const [getSummary, setSummary] = useStateMap(createStateSymbol("summary"));
 /**
- * @summary attaches a documentation string. It is typically used to give a short, single-line
+ * `@summary` attaches a documentation string. It is typically used to give a short, single-line
  * description, and can be used in combination with or instead of @doc.
  *
  * The first argument to @summary is a string, which may contain template parameters, enclosed in braces,
@@ -61,6 +62,7 @@ export const $doc = (context, target, text, sourceObject) => {
 export function getDoc(program, target) {
     return getDocDataInternal(program, target, "self")?.value;
 }
+/** Attaches documentation describing an operation's successful return types, separately from its errors. */
 export const $returnsDoc = (context, target, text) => {
     validateDecoratorUniqueOnNode(context, target, $doc);
     setDocData(context.program, target, "returns", { value: text, source: "decorator" });
@@ -83,6 +85,7 @@ export function getReturnsDocData(program, target) {
 export function getReturnsDoc(program, target) {
     return getDocDataInternal(program, target, "returns")?.value;
 }
+/** Attaches documentation describing an operation's error return types, separately from its successful results. */
 export const $errorsDoc = (context, target, text) => {
     validateDecoratorUniqueOnNode(context, target, $doc);
     setDocData(context.program, target, "errors", { value: text, source: "decorator" });
@@ -105,6 +108,7 @@ export function getErrorsDocData(program, target) {
 export function getErrorsDoc(program, target) {
     return getDocDataInternal(program, target, "errors")?.value;
 }
+/** Logs an optional nonempty label followed by the target type object, to a depth of three, for debugging. */
 export const $inspectType = (context, target, text) => {
     // eslint-disable-next-line no-console
     if (text)
@@ -112,6 +116,7 @@ export const $inspectType = (context, target, text) => {
     // eslint-disable-next-line no-console
     console.dir(target, { depth: 3 });
 };
+/** Logs an optional nonempty label followed by the target's formatted TypeSpec name for debugging. */
 export const $inspectTypeName = (context, target, text) => {
     // eslint-disable-next-line no-console
     if (text)
@@ -119,10 +124,12 @@ export const $inspectTypeName = (context, target, text) => {
     // eslint-disable-next-line no-console
     console.log(getTypeName(target));
 };
+/** Tests whether the target is a scalar assignable to the standard `string` type, including derived scalars. */
 export function isStringType(program, target) {
     const stringType = program.checker.getStdType("string");
     return (target.kind === "Scalar" && program.checker.isTypeAssignableTo(target, stringType, target)[0]);
 }
+/** Tests whether the target is a scalar assignable to the standard `numeric` type, including derived scalars. */
 export function isNumericType(program, target) {
     const numericType = program.checker.getStdType("numeric");
     return (target.kind === "Scalar" && program.checker.isTypeAssignableTo(target, numericType, target)[0]);
@@ -353,6 +360,7 @@ export function getMediaTypeHint(program, target) {
     }
 }
 // -- @format decorator ---------------------
+/** Gets the format hint stored on this type, or `undefined` if none is set; does not search base types. */
 const [getFormat, setFormat] = useStateMap(createStateSymbol("format"));
 /**
  * `@format` - specify the data format hint for a string type
@@ -377,6 +385,7 @@ export const $format = (context, target, format) => {
 export { getFormat };
 // -- @pattern decorator ---------------------
 const [getPatternData, setPatternData] = useStateMap(createStateSymbol("patternValues"));
+/** Records a string validation pattern and optional failure message, reporting invalid regular expressions. */
 export const $pattern = (context, target, pattern, validationMessage) => {
     validateDecoratorUniqueOnNode(context, target, $pattern);
     if (!validateTargetingAString(context, target, "@pattern")) {
@@ -420,6 +429,7 @@ export {
  */
 getPatternData, };
 // -- @minLength decorator ---------------------
+/** Sets an inclusive minimum string length, rejecting a bound greater than the target's maximum length. */
 export const $minLength = (context, target, minLength) => {
     validateDecoratorUniqueOnNode(context, target, $minLength);
     if (!validateTargetingAString(context, target, "@minLength") ||
@@ -429,6 +439,7 @@ export const $minLength = (context, target, minLength) => {
     setMinLength(context.program, target, minLength);
 };
 // -- @maxLength decorator ---------------------
+/** Sets an inclusive maximum string length, rejecting a bound less than the target's minimum length. */
 export const $maxLength = (context, target, maxLength) => {
     validateDecoratorUniqueOnNode(context, target, $maxLength);
     if (!validateTargetingAString(context, target, "@maxLength") ||
@@ -438,6 +449,7 @@ export const $maxLength = (context, target, maxLength) => {
     setMaxLength(context.program, target, maxLength);
 };
 // -- @minItems decorator ---------------------
+/** Sets an inclusive minimum array item count, rejecting a bound greater than the target's maximum count. */
 export const $minItems = (context, target, minItems) => {
     validateDecoratorUniqueOnNode(context, target, $minItems);
     if (!validateTargetingAnArray(context, target, "@minItems")) {
@@ -449,6 +461,7 @@ export const $minItems = (context, target, minItems) => {
     setMinItems(context.program, target, minItems);
 };
 // -- @maxLength decorator ---------------------
+/** Sets an inclusive maximum array item count, rejecting a bound less than the target's minimum count. */
 export const $maxItems = (context, target, maxItems) => {
     validateDecoratorUniqueOnNode(context, target, $maxItems);
     if (!validateTargetingAnArray(context, target, "@maxItems")) {
@@ -460,6 +473,7 @@ export const $maxItems = (context, target, maxItems) => {
     setMaxItems(context.program, target, maxItems);
 };
 // -- @minValue decorator ---------------------
+/** Sets an inclusive lower bound for a numeric or date/time scalar or property, validating assignability. */
 export const $minValue = (context, target, minValue) => {
     validateDecoratorUniqueOnNode(context, target, $minValue);
     validateDecoratorNotOnType(context, target, $minValueExclusive, $minValue);
@@ -477,6 +491,7 @@ export const $minValue = (context, target, minValue) => {
     setMinValue(program, target, minValue);
 };
 // -- @maxValue decorator ---------------------
+/** Sets an inclusive upper bound for a numeric or date/time scalar or property, validating assignability. */
 export const $maxValue = (context, target, maxValue) => {
     validateDecoratorUniqueOnNode(context, target, $maxValue);
     validateDecoratorNotOnType(context, target, $maxValueExclusive, $maxValue);
@@ -494,6 +509,7 @@ export const $maxValue = (context, target, maxValue) => {
     setMaxValue(program, target, maxValue);
 };
 // -- @minValueExclusive decorator ---------------------
+/** Sets an exclusive lower bound for a numeric or date/time scalar or property, validating assignability. */
 export const $minValueExclusive = (context, target, minValueExclusive) => {
     validateDecoratorUniqueOnNode(context, target, $minValueExclusive);
     validateDecoratorNotOnType(context, target, $minValue, $minValueExclusive);
@@ -511,6 +527,7 @@ export const $minValueExclusive = (context, target, minValueExclusive) => {
     setMinValueExclusive(program, target, minValueExclusive);
 };
 // -- @maxValueExclusive decorator ---------------------
+/** Sets an exclusive upper bound for a numeric or date/time scalar or property, validating assignability. */
 export const $maxValueExclusive = (context, target, maxValueExclusive) => {
     validateDecoratorUniqueOnNode(context, target, $maxValueExclusive);
     validateDecoratorNotOnType(context, target, $maxValue, $maxValueExclusive);
@@ -528,6 +545,7 @@ export const $maxValueExclusive = (context, target, maxValueExclusive) => {
     setMaxValueExclusive(program, target, maxValueExclusive);
 };
 // -- @secret decorator ---------------------
+/** Tests whether this type is marked with `@secret`; does not search base types. */
 const [isSecret, markSecret] = useStateSet(createStateSymbol("secretTypes"));
 /**
  * Mark a value as a secret value that should be treated carefully to avoid exposure
@@ -539,7 +557,12 @@ export const $secret = (context, target) => {
     markSecret(context.program, target);
 };
 export { isSecret };
+/** Gets encoding instructions stored on this scalar or property, or `undefined`; does not search base scalars. */
 const [getEncode, setEncodeData] = useStateMap(createStateSymbol("encode"));
+/**
+ * Records how a scalar or property is serialized, validating known encodings against the target and wire types.
+ * Named encodings default to a `string` representation; passing the `string` scalar encodes numeric or boolean values as text.
+ */
 export const $encode = (context, target, encoding, encodeAs) => {
     validateDecoratorUniqueOnNode(context, target, $encode);
     const encodeData = computeEncoding(context.program, encoding, encodeAs);
@@ -637,11 +660,16 @@ function validateEncodeData(context, target, encodeData) {
 }
 export { getEncode };
 // -- @withOptionalProperties decorator ---------------------
+/** Mutates every property in the target model's own property map to be optional; does not walk base models. */
 export const $withOptionalProperties = (context, target) => {
     // Make all properties of the target type optional
     target.properties.forEach((p) => (p.optional = true));
 };
 // -- @withoutOmittedProperties decorator ----------------------
+/**
+ * Removes named properties from the target model in place, without walking base models.
+ * Names come from a string literal or the string-literal variants of a union; other variants are ignored.
+ */
 export const $withoutOmittedProperties = (context, target, omitProperties) => {
     // Get the property or properties to omit
     const omitNames = new Set();
@@ -659,6 +687,10 @@ export const $withoutOmittedProperties = (context, target, omitProperties) => {
     filterModelPropertiesInPlace(target, (prop) => !omitNames.has(prop.name));
 };
 // -- @withPickedProperties decorator ----------------------
+/**
+ * Removes all properties except the named ones from the target model in place, without walking base models.
+ * Names come from a string literal or the string-literal variants of a union; other variants are ignored.
+ */
 export const $withPickedProperties = (context, target, pickedProperties) => {
     // Get the property or properties to pick
     const pickedNames = new Set();
@@ -676,6 +708,7 @@ export const $withPickedProperties = (context, target, pickedProperties) => {
     filterModelPropertiesInPlace(target, (prop) => pickedNames.has(prop.name));
 };
 // -- @withoutDefaultValues decorator ----------------------
+/** Deletes default values from the target model's own properties in place; does not walk base models. */
 export const $withoutDefaultValues = (context, target) => {
     // remove all read-only properties from the target type
     target.properties.forEach((p) => {
@@ -684,8 +717,7 @@ export const $withoutDefaultValues = (context, target) => {
 };
 // -- @tag decorator ---------------------
 const [getTagsState, setTags] = useStateMap(createStateSymbol("tagProperties"));
-// Set a tag on an operation, interface, or namespace.  There can be multiple tags on an
-// operation, interface, or namespace.
+/** Appends a tag to an operation, interface, or namespace; multiple tags and duplicate strings are retained. */
 export const $tag = (context, target, tag) => {
     const tags = getTagsState(context.program, target);
     if (tags) {
@@ -695,12 +727,18 @@ export const $tag = (context, target, tag) => {
         setTags(context.program, target, [tag]);
     }
 };
-// Return the tags set on an operation or namespace
+/**
+ * Gets only the tags stored directly on the target, or an empty array if none are set.
+ * The stored array is returned without copying; use {@link getAllTags} to include containing scopes.
+ */
 export function getTags(program, target) {
     return getTagsState(program, target) || [];
 }
-// Merge the tags for a operation with the tags that are on the namespace or
-// interface it resides within.
+/**
+ * Collects unique tags from the target and its enclosing interface and namespaces.
+ * Tags are collected from inner to outer scopes and the deduplicated sequence is reversed before returning.
+ * Returns a new array, or `undefined` if no scope has tags.
+ */
 export function getAllTags(program, target) {
     const tags = new Set();
     let current = target;
@@ -720,7 +758,12 @@ export function getAllTags(program, target) {
     return tags.size > 0 ? Array.from(tags).reverse() : undefined;
 }
 // -- @friendlyName decorator ---------------------
+/** Gets the friendly name stored on this type, or `undefined`; does not synthesize a name or search base types. */
 const [getFriendlyName, setFriendlyName] = useStateMap(createStateSymbol("friendlyNames"));
+/**
+ * Stores an emitter-facing name without changing the type's TypeSpec name.
+ * When a source object is supplied, its properties replace `{property}` placeholders in the name.
+ */
 export const $friendlyName = (context, target, friendlyName, sourceObject) => {
     // workaround for current lack of functionality in compiler
     // https://github.com/microsoft/typespec/issues/2717
@@ -822,7 +865,7 @@ getOverloadedOperation,
  * Get all operations that are marked as overloads of the given operation
  * @param program Program
  * @param operation Operation
- * @returns An array of operations that overload the given operation.
+ * @returns The stored array of overloads, or `undefined` if none have been registered.
  */
 getOverloads, };
 function validateRange(context, min, max) {
@@ -842,6 +885,10 @@ function validateRange(context, min, max) {
     }
     return true;
 }
+/**
+ * Configures and validates a discriminated union.
+ * Defaults to an object envelope with discriminator property `kind` and value property `value`.
+ */
 export const discriminatedDecorator = (context, entity, options = {}) => {
     setDiscriminatedOptions(context.program, entity, {
         envelope: "object",
@@ -852,10 +899,15 @@ export const discriminatedDecorator = (context, entity, options = {}) => {
     const [_, diagnostics] = getDiscriminatedUnion(context.program, entity);
     context.program.reportDiagnostics(diagnostics);
 };
+/** Records the property used to distinguish a model's derived variants during serialization. */
 export const $discriminator = (context, entity, propertyName) => {
     setDiscriminator(context.program, entity, { propertyName });
 };
 const [getExamplesState, setExamples] = useStateMap(createStateSymbol("examples"));
+/**
+ * Appends an example and optional display metadata to the target after checking value assignability.
+ * Reads the original TypeSpec value from the decorator application rather than the marshalled JS argument.
+ */
 export const $example = (context, target, _example, options) => {
     const decorator = target.decorators.find((d) => d.decorator === $example && d.node === context.decoratorTarget);
     compilerAssert(decorator, `Couldn't find @example decorator`, context.decoratorTarget);
@@ -873,10 +925,18 @@ export const $example = (context, target, _example, options) => {
     }
     list.push({ value: rawExample, ...options });
 };
+/**
+ * Gets examples stored on the target in registration order, or an empty array.
+ * Returns the stored collection as readonly without copying; values remain TypeSpec values, not JSON.
+ */
 export function getExamples(program, target) {
     return getExamplesState(program, target) ?? [];
 }
 const [getOpExamplesState, setOpExamples] = useStateMap(createStateSymbol("opExamples"));
+/**
+ * Appends example parameter and result values with optional display metadata, checking each supplied value's assignability.
+ * Reads original TypeSpec values from the decorator application rather than the marshalled JS argument.
+ */
 export const $opExample = (context, target, _example, options) => {
     const decorator = target.decorators.find((d) => d.decorator === $opExample && d.node === context.decoratorTarget);
     compilerAssert(decorator, `Couldn't find @opExample decorator`, context.decoratorTarget);
@@ -909,6 +969,10 @@ function checkExampleValid(program, value, target, diagnosticTarget) {
     }
     return assignable;
 }
+/**
+ * Gets operation examples in registration order, or an empty array if none are set.
+ * Returns the stored array without copying; parameter and result values have not been serialized.
+ */
 export function getOpExamples(program, target) {
     return getOpExamplesState(program, target) ?? [];
 }