expanded card and layout documentation

Author: scarletcs

src/objects/Card/Card.ts

@@ -10,6 +10,35 @@ type Layout<T extends ScryfallLayout> = Pick<ScryfallCardFields.Core.All, "layou
 /**
  * A collection of types representing Scryfall cards of each possible layout.
  *
+ *
+ * An individual type exists for each possible layout: {@link ScryfallCard.Normal}, {@link ScryfallCard.Transform}, etc.
+ *
+ * Then various groups exist to help describe cards of indeterminate layout:
+ * - {@link ScryfallCard.Any} describes any card at all. Think of it as like `any` but for cards.
+ * - {@link ScryfallCard.AnySingleFaced} describes any card with one face and no `card_faces` property, e.g. {@link ScryfallCard.Normal Normal} or {@link ScryfallCard.Saga Saga}.
+ * - {@link ScryfallCard.AnyMultiFaced} describes any card with multiple faces. It may be a split card with both "faces" on the front, or a double-sided card with faces on the front and back of the card. It also collects the next two groups on this list.
+ * - {@link ScryfallCard.AnySingleSidedSplit} describes any card with multiple faces where both faces are on the front, e.g. {@link ScryfallCard.Adventure Adventure}, {@link ScryfallCard.Flip Flip}, or {@link ScryfallCard.Split Split}.
+ * - {@link ScryfallCard.AnyDoubleSidedSplit} describes any card with multiple faces where the faces are on the front and back of the card, e.g.  {@link ScryfallCard.Transform Transform},  {@link ScryfallCard.ModalDfc ModalDfc}, or  {@link ScryfallCard.ReversibleCard ReversibleCard}.
+ *
+ * We recommend starting from `ScryfallCard.Any` to describe generic API responses, and you will need to do type narrowing to access more specific fields.
+ *
+ * @example // Type narrowing by layout
+ * const mysteryCard: ScryfallCard.Any = getCard();
+ *
+ * if (mysteryCard.layout === ScryfallLayout.Transform) {
+ *   const transform: ScryfallCard.Transform = mysteryCard;
+ * }
+ *
+ * @example // Type narrowing by property
+ * const mysteryCard: ScryfallCard.Any = getCard();
+ *
+ * if ("card_faces" in mysteryCard) {
+ *   const mfc: ScryfallCard.AnyMultiFaced = mysteryCard;
+ * } else {
+ *   const sfc: ScryfallCard.AnySingleFaced = mysteryCard;
+ * }
+ *
+ *
  * @see {@link https://scryfall.com/docs/api/cards}
  * @see {@link https://scryfall.com/docs/api/layouts}
  */

src/objects/Card/values/Layout.ts

@@ -1,3 +1,6 @@
+/**
+ * The set of card layouts.
+ */
 export enum ScryfallLayout {
   /** A standard Magic card with one face */
   Normal = "normal",
@@ -49,7 +52,13 @@ export enum ScryfallLayout {
 
 export type ScryfallLayoutLike = ScryfallLayout | `${ScryfallLayout}`;
 
+/**
+ * Groupings of layouts.
+ */
 export namespace ScryfallLayoutGroup {
+  /**
+   * A type describing all layouts that represent a single-faced card, i.e. one with no card_faces property.
+   */
   export type SingleFaceType =
     | ScryfallLayout.Normal
     | ScryfallLayout.Meld
@@ -67,6 +76,9 @@ export namespace ScryfallLayoutGroup {
     | ScryfallLayout.Augment
     | ScryfallLayout.Host;
 
+  /**
+   * A type describing all layouts that represent a multi-faced card, i.e. one with a card_faces property.
+   */
   export type MultiFaceType =
     | ScryfallLayout.Split
     | ScryfallLayout.Flip
@@ -77,8 +89,14 @@ export namespace ScryfallLayoutGroup {
     | ScryfallLayout.ArtSeries
     | ScryfallLayout.ReversibleCard;
 
+  /**
+   * A card describing all layouts that represent a multi-faced card where both faces are on the front.
+   */
   export type SingleSidedSplitType = ScryfallLayout.Split | ScryfallLayout.Flip | ScryfallLayout.Adventure;
 
+  /**
+   * A card describing all layouts that represent a multi-faced card where the faces are on the front and back of the card.
+   */
   export type DoubleSidedSplitType =
     | ScryfallLayout.Transform
     | ScryfallLayout.ModalDfc