Expand documentation for new layout directives

Includes a fix for generate-symbol-graph doc comment fetching for directives
implemented by a class with a different name.

rdar://108207445

Author: daniel-grumberg

Sources/SwiftDocC/Semantics/DirectiveInfrastructure/DirectiveIndex.swift

@@ -104,4 +104,12 @@ struct DirectiveIndex {
         // is not in the pre-populated index.
         return indexedDirectives[directiveConvertible.directiveName]!
     }
+    
+    func reflection(of implementationName: String) -> DirectiveMirror.ReflectedDirective? {
+        return indexedDirectives.first(
+            where: { (directiveName: String, reflectedDirective: DirectiveMirror.ReflectedDirective) in
+                directiveName == implementationName || String(describing: reflectedDirective.type) == implementationName
+            }
+        )?.value
+    }
 }

Sources/SwiftDocC/Semantics/Metadata/PageImage.swift

@@ -11,19 +11,28 @@
 import Foundation
 import Markdown
 
+/// Associates an image with a page.
+///
+/// You can use this directive to set the image used when rendering a user-interface element representing the page.
+/// For example, use the page image directive to customize the icon used to represent this page in the navigation sidebar,
+/// or the card image used to represent this page when using the ``Links`` directive and the ``Links/detailedGrid``
+/// visual style.
 public final class PageImage: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
+    /// The image's purpose.
     @DirectiveArgumentWrapped
     public private(set) var purpose: Purpose
 
+    /// The base file name of an image in your documentation catalog.
     @DirectiveArgumentWrapped(
         parseArgument: { bundle, argumentValue in
             ResourceReference(bundleIdentifier: bundle.identifier, path: argumentValue)
         }
     )
     public private(set) var source: ResourceReference
 
+    /// Alternative text that describes the image to screen readers.
     @DirectiveArgumentWrapped
     public private(set) var alt: String? = nil
 
@@ -33,10 +42,12 @@ public final class PageImage: Semantic, AutomaticDirectiveConvertible {
         "alt"       : \PageImage._alt,
     ]
 
-    /// The style of the display name for this symbol.
+    /// The name of the display style for this image.
     public enum Purpose: String, CaseIterable, DirectiveArgumentValueConvertible {
+        /// The image will be used when representing the page as an icon, such as in the navigation sidebar.
         case icon
 
+        /// The image will be used when representing the page as a card, such as in grid styled Topics sections.
         case card
     }
 

Sources/SwiftDocC/Semantics/Options/AutomaticTitleHeading.swift

@@ -25,7 +25,7 @@ public class AutomaticTitleHeading: Semantic, AutomaticDirectiveConvertible {
     @DirectiveArgumentWrapped(name: .unnamed)
     public private(set) var enabledness: Enabledness
 
-    /// A value that represent whether automatic title heading generation is enabled or disabled.
+    /// A value that represents whether automatic title heading generation is enabled or disabled.
     public enum Enabledness: String, CaseIterable, DirectiveArgumentValueConvertible {
         /// A title heading should be automatically created for the page (the default).
         case enabled

Sources/SwiftDocC/Semantics/Options/Options.swift

@@ -11,7 +11,7 @@
 import Foundation
 import Markdown
 
-/// Use Option directives to adjust DocC's default behaviors when rendering a page.
+/// A directive to adjust Swift-DocC's default behaviors when rendering a page.
 ///
 /// ## Topics
 ///

Sources/SwiftDocC/Semantics/Reference/Row.swift

@@ -50,6 +50,7 @@ import Markdown
 public final class Row: Semantic, AutomaticDirectiveConvertible, MarkupContaining {
     public let originalMarkup: BlockDirective
 
+    /// The number of columns available in this row.
     @DirectiveArgumentWrapped(name: .custom("numberOfColumns"))
     public private(set) var _numberOfColumns: Int? = nil
 
@@ -89,6 +90,8 @@ public final class Row: Semantic, AutomaticDirectiveConvertible, MarkupContainin
 extension Row {
     /// A container directive that holds general markup content describing a column
     /// with a row in a grid-based layout.
+    ///
+    /// Create a column inside a ``Row`` by nesting a `@Column` directive within the content for an `@Row` directive.
     public final class Column: Semantic, AutomaticDirectiveConvertible, MarkupContaining {
         public let originalMarkup: BlockDirective
 

Sources/SwiftDocC/Semantics/Reference/TabNavigator.swift

@@ -61,6 +61,8 @@ public final class TabNavigator: Semantic, AutomaticDirectiveConvertible, Markup
 extension TabNavigator {
     /// A container directive that holds general markup content describing an individual
     /// tab within a tab-based layout.
+    ///
+    ///  To add a new tab to a ``TabNavigator``, add  a `@Tab` directive within the content of the `@TabNavigator` directive.
     public final class Tab: Semantic, AutomaticDirectiveConvertible, MarkupContaining {
         public let originalMarkup: BlockDirective
 

Sources/docc/DocCDocumentation.docc/DocC.symbols.json

@@ -600,6 +600,118 @@
           "spelling" : ")"
         }
       ],
+      "docComment" : {
+        "lines" : [
+          {
+            "text" : "A directive that sets the platform availability information for a documentation page."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "`@Available` is analagous to the `@available` attribute in Swift: It allows you to specify a"
+          },
+          {
+            "text" : "platform version that the page relates to. To specify a platform and version, list the platform"
+          },
+          {
+            "text" : "name and use the `introduced` argument:"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "```markdown"
+          },
+          {
+            "text" : "@Available(macOS, introduced: \"12.0\")"
+          },
+          {
+            "text" : "```"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "Any text can be given to the first argument, and will be displayed in the page's"
+          },
+          {
+            "text" : "availability data. The platforms `iOS`, `macOS`, `watchOS`, and `tvOS` will be matched"
+          },
+          {
+            "text" : "case-insensitively, but anything else will be printed verbatim."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "To provide a platform name with spaces in it, provide it as a quoted string:"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "```markdown"
+          },
+          {
+            "text" : "@Available(\"My Package\", introduced: \"1.0\")"
+          },
+          {
+            "text" : "```"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "This directive is available on both articles and documentation extension files. In extension"
+          },
+          {
+            "text" : "files, the information overrides any information from the symbol itself."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "This directive is only valid within a ``Metadata`` directive:"
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "```markdown"
+          },
+          {
+            "text" : "@Metadata {"
+          },
+          {
+            "text" : "    @Available(macOS, introduced: \"12.0\")"
+          },
+          {
+            "text" : "    @Available(iOS, introduced: \"15.0\")"
+          },
+          {
+            "text" : "}"
+          },
+          {
+            "text" : "```"
+          },
+          {
+            "text" : "- Parameters:"
+          },
+          {
+            "text" : "  - platform: The platform that this argument's information applies to."
+          },
+          {
+            "text" : "     **(required)**"
+          },
+          {
+            "text" : "  - introduced: The platform version that this page applies to."
+          },
+          {
+            "text" : "     **(required)**"
+          }
+        ]
+      },
       "identifier" : {
         "interfaceLanguage" : "swift",
         "precise" : "__docc_universal_symbol_reference_$Available"
@@ -1492,6 +1604,12 @@
           {
             "text" : "with a row in a grid-based layout."
           },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "Create a column inside a ``Row`` by nesting a `@Column` directive within the content for an `@Row` directive."
+          },
           {
             "text" : "- Parameters:"
           },
@@ -2262,6 +2380,28 @@
           "spelling" : " {\n    ...\n}"
         }
       ],
+      "docComment" : {
+        "lines" : [
+          {
+            "text" : "A block filled with an image."
+          },
+          {
+            "text" : "- Parameters:"
+          },
+          {
+            "text" : "  - source: A reference to the source file for the media item."
+          },
+          {
+            "text" : "     **(required)**"
+          },
+          {
+            "text" : "  - alt: Optional alternate text for an image."
+          },
+          {
+            "text" : "     **(optional)**"
+          }
+        ]
+      },
       "identifier" : {
         "interfaceLanguage" : "swift",
         "precise" : "__docc_universal_symbol_reference_$Image"
@@ -2957,7 +3097,7 @@
       "docComment" : {
         "lines" : [
           {
-            "text" : "Use Option directives to adjust DocC's default behaviors when rendering a page."
+            "text" : "A directive to adjust Swift-DocC's default behaviors when rendering a page."
           },
           {
             "text" : ""
@@ -3320,6 +3460,55 @@
           "spelling" : ")"
         }
       ],
+      "docComment" : {
+        "lines" : [
+          {
+            "text" : "Associates an image with a page."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "You can use this directive to set the image used when rendering a user-interface element representing the page."
+          },
+          {
+            "text" : "For example, use the page image directive to customize the icon used to represent this page in the navigation sidebar,"
+          },
+          {
+            "text" : "or the card image used to represent this page when using the ``Links`` directive and the ``Links\/detailedGrid``"
+          },
+          {
+            "text" : "visual style."
+          },
+          {
+            "text" : "- Parameters:"
+          },
+          {
+            "text" : "  - purpose: The image's purpose."
+          },
+          {
+            "text" : "     **(required)**"
+          },
+          {
+            "text" : "     - term `icon`: The image will be used when representing the page as an icon, such as in the navigation sidebar."
+          },
+          {
+            "text" : "     - term `card`: The image will be used when representing the page as a card, such as in grid styled Topics sections."
+          },
+          {
+            "text" : "  - source: The base file name of an image in your documentation catalog."
+          },
+          {
+            "text" : "     **(required)**"
+          },
+          {
+            "text" : "  - alt: Alternative text that describes the image to screen readers."
+          },
+          {
+            "text" : "     **(optional)**"
+          }
+        ]
+      },
       "identifier" : {
         "interfaceLanguage" : "swift",
         "precise" : "__docc_universal_symbol_reference_$PageImage"
@@ -3814,7 +4003,7 @@
             "text" : "- Parameters:"
           },
           {
-            "text" : "  - numberOfColumns: The number of columns in this row."
+            "text" : "  - numberOfColumns: The number of columns available in this row."
           },
           {
             "text" : "     **(optional)**"
@@ -4536,6 +4725,12 @@
           {
             "text" : "tab within a tab-based layout."
           },
+          {
+            "text" : ""
+          },
+          {
+            "text" : " To add a new tab to a ``TabNavigator``, add  a `@Tab` directive within the content of the `@TabNavigator` directive."
+          },
           {
             "text" : "- Parameters:"
           },
@@ -5469,6 +5664,34 @@
           "spelling" : " {\n    ...\n}"
         }
       ],
+      "docComment" : {
+        "lines" : [
+          {
+            "text" : "A block filled with a video."
+          },
+          {
+            "text" : "- Parameters:"
+          },
+          {
+            "text" : "  - source: A reference to the source file for the media item."
+          },
+          {
+            "text" : "     **(required)**"
+          },
+          {
+            "text" : "  - alt: Alternate text describing the video."
+          },
+          {
+            "text" : "     **(optional)**"
+          },
+          {
+            "text" : "  - poster: An image to be shown when the video isn't playing."
+          },
+          {
+            "text" : "     **(optional)**"
+          }
+        ]
+      },
       "identifier" : {
         "interfaceLanguage" : "swift",
         "precise" : "__docc_universal_symbol_reference_$Video"