From d1ba184949bc90d6bdcec403bd58dced3263db6a Mon Sep 17 00:00:00 2001
From: "Craig Macomber (Microsoft)"
 <42876482+CraigMacomber@users.noreply.github.com>
Date: Fri, 8 Nov 2024 18:10:20 -0800
Subject: [PATCH] docs: Add more ImplicitAllowedTypes docs (#23045)

## Description

Add more ImplicitAllowedTypes docs
---
 .../dds/tree/src/simple-tree/schemaTypes.ts   | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/dds/tree/src/simple-tree/schemaTypes.ts b/packages/dds/tree/src/simple-tree/schemaTypes.ts
index 61d4cc78145b..83979f815c25 100644
--- a/packages/dds/tree/src/simple-tree/schemaTypes.ts
+++ b/packages/dds/tree/src/simple-tree/schemaTypes.ts
@@ -476,9 +476,34 @@ function evaluateLazySchema(value: LazyItem<TreeNodeSchema>): TreeNodeSchema {
 }
 
 /**
- * Types allowed in a field.
+ * Types of {@link TreeNode|TreeNodes} or {@link TreeLeafValue|TreeLeafValues} allowed at a location in a tree.
  * @remarks
+ * Used by {@link TreeViewConfiguration} for the root and various kinds of {@link TreeNodeSchema} to specify their allowed child types.
+ *
+ * Use {@link SchemaFactory} to access leaf schema or declare new composite schema.
+ *
  * Implicitly treats a single type as an array of one type.
+ *
+ * Arrays of schema can be used to specify multiple types are allowed, which result in unions of those types in the Tree APIs.
+ *
+ * When saved into variables, avoid type-erasing the details, as doing so loses the compile time schema awareness of APIs derived from the types.
+ *
+ * When referring to types that are declared after the definition of the `ImplicitAllowedTypes`, the schema can be wrapped in a lambda to allow the forward reference.
+ * See {@link ValidateRecursiveSchema} for details on how to structure the `ImplicitAllowedTypes` instances when constructing recursive schema.
+ *
+ * @example Explicit use with strong typing
+ * ```typescript
+ * const sf = new SchemaFactory("myScope");
+ * const childTypes = [sf.number, sf.string] as const satisfies ImplicitAllowedTypes;
+ * const config = new TreeViewConfiguration({ schema: childTypes });
+ * ```
+ *
+ * @example Forward reference
+ * ```typescript
+ * const sf = new SchemaFactory("myScope");
+ * class A extends sf.array("example", [() => B]) {}
+ * class B extends sf.array("Inner", sf.number) {}
+ * ```
  * @public
  */
 export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;