Add docs for boolean, array, object and format enums

Author: andrewheard

FirebaseVertexAI/Sources/Schema.swift

@@ -19,13 +19,19 @@ import Foundation
 /// These types can be objects, but also primitives and arrays. Represents a select subset of an
 /// [OpenAPI 3.0 schema object](https://spec.openapis.org/oas/v3.0.3#schema).
 public class Schema {
+  /// Modifiers describing the expected format of a string `Schema`.
   public enum StringFormat {
+    /// A custom string format.
     case custom(String)
   }
 
+  /// Modifiers describing the expected format of an integer `Schema`.
   public enum IntegerFormat {
+    /// A 32-bit signed integer.
     case int32
+    /// A 64-bit signed integer.
     case int64
+    /// A custom integer format.
     case custom(String)
   }
 
@@ -105,7 +111,7 @@ public class Schema {
   /// Returns a `Schema` representing a string value.
   ///
   /// This schema instructs the model to produce data of type ``DataType/string``, which is suitable
-  /// for decoding as a Swift `String` (or `String?`, if ``nullable`` is set to `true`).
+  /// for decoding into a Swift `String` (or `String?`, if `nullable` is set to `true`).
   ///
   /// > Tip: If a specific set of string values should be generated by the model (for example,
   /// > "north", "south", "east", or "west"), use ``enumeration(values:description:nullable:)``
@@ -134,8 +140,8 @@ public class Schema {
   /// Returns a `Schema` representing an enumeration of string values.
   ///
   /// This schema instructs the model to produce data of type ``DataType/string`` with the
-  /// ``format`` `"enum"`. This data is suitable for decoding as a Swift `String` (or `String?`,
-  /// if ``nullable`` is set to `true`), or an `enum` with strings as raw values.
+  /// `format` `"enum"`. This data is suitable for decoding into a Swift `String` (or `String?`,
+  /// if `nullable` is set to `true`), or an `enum` with strings as raw values.
   ///
   /// **Example:**
   /// The values `["north", "south", "east", "west"]` for an enumation of directions.
@@ -166,8 +172,8 @@ public class Schema {
   /// Returns a `Schema` representing a single-precision floating-point number.
   ///
   /// This schema instructs the model to produce data of type ``DataType/number`` with the
-  /// ``format`` `"float"`, which is suitable for decoding as a Swift `Float` (or `Float?`, if
-  /// ``nullable`` is set to `true`).
+  /// `format` `"float"`, which is suitable for decoding into a Swift `Float` (or `Float?`, if
+  /// `nullable` is set to `true`).
   ///
   /// > Important: This `Schema` provides a hint to the model that it should generate a
   /// > single-precision floating-point number, a `float`, but only guarantees that the value will
@@ -190,8 +196,8 @@ public class Schema {
   /// Returns a `Schema` representing a double-precision floating-point number.
   ///
   /// This schema instructs the model to produce data of type ``DataType/number`` with the
-  /// ``format`` `"double"`, which is suitable for decoding as a Swift `Double` (or `Double?`, if
-  /// ``nullable`` is set to `true`).
+  /// `format` `"double"`, which is suitable for decoding into a Swift `Double` (or `Double?`, if
+  /// `nullable` is set to `true`).
   ///
   /// > Important: This `Schema` provides a hint to the model that it should generate a
   /// > double-precision floating-point number, a `double`, but only guarantees that the value will
@@ -214,13 +220,13 @@ public class Schema {
   /// Returns a `Schema` representing an integer value.
   ///
   /// This schema instructs the model to produce data of type ``DataType/integer``, which is
-  /// suitable for decoding as a Swift `Int` (or `Int?`, if ``nullable`` is set to `true`) or other
+  /// suitable for decoding into a Swift `Int` (or `Int?`, if `nullable` is set to `true`) or other
   /// integer types (such as `Int32`) based on the expected size of values being generated.
   ///
-  /// > Important: If a ``format`` of ``IntegerFormat/int32`` or ``IntegerFormat/int64`` is
+  /// > Important: If a `format` of ``IntegerFormat/int32`` or ``IntegerFormat/int64`` is
   /// > specified, this provides a hint to the model that it should generate 32-bit or 64-bit
   /// > integers but this `Schema` only guarantees that the value will be an integer. Therefore, it
-  /// > is *possible* that decoding as an `Int32` could overflow even if a ``format`` of
+  /// > is *possible* that decoding into an `Int32` could overflow even if a `format` of
   /// > ``IntegerFormat/int32`` is specified.
   ///
   /// - Parameters:
@@ -241,15 +247,70 @@ public class Schema {
     )
   }
 
+  /// Returns a `Schema` representing a boolean value.
+  ///
+  /// This schema instructs the model to produce data of type ``DataType/boolean``, which is
+  /// suitable for decoding into a Swift `Bool` (or `Bool?`, if `nullable` is set to `true`).
+  ///
+  /// - Parameters:
+  ///   - description: An optional description of what the boolean should contain or represent; may
+  ///   use Markdown format.
+  ///   - nullable: If `true`, instructs the model that it may return `null` instead of a boolean;
+  ///   defaults to `false`, enforcing that a boolean is returned.
   public static func boolean(description: String? = nil, nullable: Bool = false) -> Schema {
     return self.init(type: .boolean, description: description, nullable: nullable)
   }
 
+  /// Returns a `Schema` representing an array.
+  ///
+  /// This schema instructs the model to produce data of type ``DataType/array``, which has elements
+  /// of any other ``DataType`` (including nested ``DataType/array``s). This data is suitable for
+  /// decoding into many Swift collection types, including `Array`, holding elements of types
+  /// suitable for decoding from the respective `items` type.
+  ///
+  /// - Parameters:
+  ///   - items: The `Schema` of the elements that the array will hold.
+  ///   - description: An optional description of what the array should contain or represent; may
+  ///   use Markdown format.
+  ///   - nullable: If `true`, instructs the model that it may return `null` instead of an array;
+  ///   defaults to `false`, enforcing that an array is returned.
   public static func array(items: Schema, description: String? = nil,
                            nullable: Bool = false) -> Schema {
     return self.init(type: .array, description: description, nullable: nullable, items: items)
   }
 
+  /// Returns a `Schema` representing an object.
+  ///
+  /// This schema instructs the model to produce data of type ``DataType/object``, which has keys
+  /// of type ``DataType/string`` and values of any other ``DataType`` (including nested
+  /// ``DataType/object``s). This data is suitable for decoding into Swift keyed collection types,
+  /// including `Dictionary`, or other custom `struct` or `class` types.
+  ///
+  /// **Example:** A `City` could be represented with the following object `Schema`.
+  /// ```
+  /// Schema.object(properties: [
+  ///   "name" : .string(),
+  ///   "population": .integer()
+  /// ])
+  /// ```
+  /// The generated data could be decoded into a Swift native type:
+  /// ```
+  /// struct City: Decodable {
+  ///   let name: String
+  ///   let population: Int
+  /// }
+  /// ```
+  ///
+  /// - Parameters:
+  ///   - properties: A dictionary containing the object's property names as keys and their
+  ///   respective `Schema`s as values.
+  ///   - optionalProperties: A list of property names that may be be omitted in objects generated
+  ///   by the model; these names must correspond to the keys provided in the `properties`
+  ///   dictionary and may be an empty list.
+  ///   - description: An optional description of what the object should contain or represent; may
+  ///   use Markdown format.
+  ///   - nullable: If `true`, instructs the model that it may return `null` instead of an object;
+  ///   defaults to `false`, enforcing that an object is returned.
   public static func object(properties: [String: Schema], optionalProperties: [String] = [],
                             description: String? = nil, nullable: Bool = false) -> Schema {
     var requiredProperties = Set(properties.keys)