Autogenerate directive documentation based on models in SwiftDocC framework (#447)

* Fix existing broken documentation

Merging the SwiftDocC’s conceptual documentation
into the `docc` executable documentation broke
documentation building in some ways when building in Xcode.

This just resolves the existing issues.

* Mark all existing documentation extensions as overriding

Prepares for adding documentation comment to the autogenerated
symbol graph by marking existing documentation extensions as overriding.

Eventually we can merge some of this documentation back into the
source.

* Autogenerate directive documentation

Autogenerate documentation for directives based on what
is defined in SwiftDocC framework source.

rdar://103925835

Author: ethan-kusters

Package.swift

@@ -100,6 +100,7 @@ let package = Package(
         .executableTarget(
             name: "generate-symbol-graph",
             dependencies: [
+                "SwiftDocC",
                 "SymbolKit",
             ]
         ),

Sources/SwiftDocC/Semantics/DirectiveInfrastructure/AutomaticDirectiveConvertible.swift

@@ -70,6 +70,9 @@ protocol AutomaticDirectiveConvertible: DirectiveConvertible, Semantic {
     ///         }
     ///     }
     static var keyPaths: [String : AnyKeyPath] { get }
+    
+    /// A Boolean value that is true if this directive should be hidden from documentation.
+    static var hiddenFromDocumentation: Bool { get }
 }
 
 extension AutomaticDirectiveConvertible {
@@ -85,6 +88,8 @@ extension AutomaticDirectiveConvertible {
     ) -> Bool {
         return true
     }
+    
+    public static var hiddenFromDocumentation: Bool { false }
 }
 
 extension AutomaticDirectiveConvertible {
@@ -234,7 +239,7 @@ extension AutomaticDirectiveConvertible {
 
                 guard let parsedDirective = parsedDirective else {
                     if childDirective.storedAsArray && !childDirective.storedAsOptional {
-                        childDirective.setValue(on: self, to: [])
+                        childDirective.setValue(on: self, to: [parsedDirective].compactMap { $0 })
                     }
 
                     continue

Sources/SwiftDocC/Semantics/DirectiveInfrastructure/DirectiveArgumentWrapper.swift

@@ -98,8 +98,8 @@ public struct DirectiveArgumentWrapped<Value>: _DirectiveArgumentProtocol {
     ) {
         self.name = name
         self.defaultValue = value
-        if let optionallyWrappedValue = Value.self as? OptionallyWrapped {
-            self.typeDisplayName = String(describing: optionallyWrappedValue.baseType())
+        if let optionallyWrappedValue = Value.self as? OptionallyWrapped.Type {
+            self.typeDisplayName = String(describing: optionallyWrappedValue.baseType()) + "?"
         } else {
             self.typeDisplayName = String(describing: Value.self)
         }
@@ -176,7 +176,13 @@ extension DirectiveArgumentWrapped where Value: DirectiveArgumentValueConvertibl
     ) {
         self.name = name
         self.defaultValue = value
-        self.typeDisplayName = String(describing: Value.self)
+        
+        if let value = value {
+            self.typeDisplayName = String(describing: Value.self) + " = " + String(describing: value)
+        } else {
+            self.typeDisplayName = String(describing: Value.self)
+        }
+        
         self.parseArgument = { _, argument in
             Value.init(rawDirectiveArgumentValue: argument)
         }
@@ -197,7 +203,12 @@ extension DirectiveArgumentWrapped where Value: OptionallyWrappedDirectiveArgume
 
         self.name = name
         self.defaultValue = wrappedValue
-        self.typeDisplayName = String(describing: argumentValueType)
+        if required {
+            self.typeDisplayName = String(describing: argumentValueType)
+        } else {
+            self.typeDisplayName = String(describing: argumentValueType) + "?"
+        }
+        
         self.parseArgument = { _, argument in
             argumentValueType.init(rawDirectiveArgumentValue: argument)
         }

Sources/SwiftDocC/Semantics/DirectiveInfrastructure/DirectiveIndex.swift

@@ -11,7 +11,7 @@
 import Foundation
 
 struct DirectiveIndex {
-    private static let topLevelReferenceDirectives: [AutomaticDirectiveConvertible.Type] = [
+    static let topLevelReferenceDirectives: [AutomaticDirectiveConvertible.Type] = [
         Metadata.self,
         Redirect.self,
         Snippet.self,
@@ -25,7 +25,7 @@ struct DirectiveIndex {
         VideoMedia.self,
     ]
 
-    private static let topLevelTutorialDirectives: [AutomaticDirectiveConvertible.Type] = [
+    static let topLevelTutorialDirectives: [AutomaticDirectiveConvertible.Type] = [
         Tutorial.self,
     ]
 

Sources/SwiftDocC/Semantics/DirectiveInfrastructure/DirectiveMirror.swift

@@ -200,6 +200,10 @@ extension DirectiveMirror {
             return type.directiveName
         }
 
+        var required: Bool {
+            return requirements == .one || requirements == .oneOrMore
+        }
+        
         let propertyLabel: String
         let childDirective: _ChildDirectiveProtocol
 
@@ -258,6 +262,10 @@ extension DirectiveMirror {
             }
         }
 
+        var hiddenFromDocumentation: Bool {
+            (type as? AutomaticDirectiveConvertible.Type)?.hiddenFromDocumentation ?? false
+        }
+        
         let type: DirectiveConvertible.Type
     }
 

Sources/SwiftDocC/Semantics/Media/ImageMedia.swift

@@ -17,6 +17,13 @@ public final class ImageMedia: Semantic, Media, AutomaticDirectiveConvertible {
 
     public let originalMarkup: BlockDirective
 
+    @DirectiveArgumentWrapped(
+        parseArgument: { bundle, argumentValue in
+            ResourceReference(bundleIdentifier: bundle.identifier, path: argumentValue)
+        }
+    )
+    public private(set) var source: ResourceReference
+    
     /// Optional alternate text for an image.
     @DirectiveArgumentWrapped(name: .custom("alt"))
     public private(set) var altText: String? = nil
@@ -25,13 +32,6 @@ public final class ImageMedia: Semantic, Media, AutomaticDirectiveConvertible {
     @ChildMarkup(numberOfParagraphs: .zeroOrOne)
     public private(set) var caption: MarkupContainer
 
-    @DirectiveArgumentWrapped(
-        parseArgument: { bundle, argumentValue in
-            ResourceReference(bundleIdentifier: bundle.identifier, path: argumentValue)
-        }
-    )
-    public private(set) var source: ResourceReference
-    
     static var keyPaths: [String : AnyKeyPath] = [
         "altText" : \ImageMedia._altText,
         "source"  : \ImageMedia._source,

Sources/SwiftDocC/Semantics/Metadata/CallToAction.swift

@@ -65,7 +65,8 @@ public final class CallToAction: Semantic, AutomaticDirectiveConvertible {
     @DirectiveArgumentWrapped
     public var purpose: Purpose? = nil
 
-    /// Text to use as the button label, which may override ``purpose-swift.property``.
+    /// Text to use as the button label, which may override the default provided by a
+    /// given `purpose`.
     @DirectiveArgumentWrapped
     public var label: String? = nil
 

Sources/SwiftDocC/Semantics/Metadata/CustomMetadata.swift

@@ -35,6 +35,8 @@ public final class CustomMetadata: Semantic, AutomaticDirectiveConvertible {
     @DirectiveArgumentWrapped
     public var value: String
 
+    static var hiddenFromDocumentation = true
+    
     static var keyPaths: [String : AnyKeyPath] = [
         "key" : \CustomMetadata._key,
         "value"  : \CustomMetadata._value,

Sources/SwiftDocC/Semantics/Options/Options.swift

@@ -11,7 +11,19 @@
 import Foundation
 import Markdown
 
-/// A directive that specifies various options for the page.
+/// Use Option directives to adjust DocC's default behaviors when rendering a page.
+///
+/// ## Topics
+///
+/// ### Adjusting Automatic Behaviors
+///
+/// - ``AutomaticSeeAlso``
+/// - ``AutomaticTitleHeading``
+/// - ``AutomaticArticleSubheading``
+///
+/// ### Adjusting Visual Style
+///
+/// - ``TopicsVisualStyle``
 public class Options: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 

Sources/SwiftDocC/Semantics/Redirect.swift

@@ -30,6 +30,8 @@ public final class Redirect: Semantic, AutomaticDirectiveConvertible {
         "oldPath" : \Redirect._oldPath,
     ]
 
+    static var hiddenFromDocumentation = true
+    
     init(originalMarkup: BlockDirective, oldPath: URL) {
         self.originalMarkup = originalMarkup
         super.init()