Update option directive naming (#448)

* Rename enabled/disabled argument for option directives

* Use property wrapper initializer for custom true/false spellings

* Improve readability of comparison with nil coalesced value

* Switch back to an Enabledness enum but keep the Bool computed property

* Generate a new symbol graph file for directives

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/Topic Graph/AutomaticCuration.swift

@@ -123,12 +123,9 @@ public struct AutomaticCuration {
         renderContext: RenderContext?,
         renderer: DocumentationContentRenderer
     ) throws -> TaskGroup? {
-        if let automaticSeeAlsoOption = node.options?.automaticSeeAlsoBehavior
-            ?? context.options?.automaticSeeAlsoBehavior
+        if (node.options?.automaticSeeAlsoEnabled ?? context.options?.automaticSeeAlsoEnabled) == false
         {
-            guard automaticSeeAlsoOption == .siblingPages else {
-                return nil
-            }
+            return nil
         }
 
         // First try getting the canonical path from a render context, default to the documentation context

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -1112,27 +1112,15 @@ public struct RenderNodeTranslator: SemanticVisitor {
     }
 
     private func shouldCreateAutomaticRoleHeading(for node: DocumentationNode) -> Bool {
-        var shouldCreateAutomaticRoleHeading = true
-        if let automaticTitleHeadingOption = node.options?.automaticTitleHeadingBehavior
-            ?? context.options?.automaticTitleHeadingBehavior
-        {
-            shouldCreateAutomaticRoleHeading = automaticTitleHeadingOption == .pageKind
-        }
-        
-        return shouldCreateAutomaticRoleHeading
+        return node.options?.automaticTitleHeadingEnabled
+            ?? context.options?.automaticTitleHeadingEnabled
+            ?? true
     }
 
     private func shouldCreateAutomaticArticleSubheading(for node: DocumentationNode) -> Bool {
-        let shouldCreateAutomaticArticleSubheading: Bool
-        if let automaticSubheadingOption = node.options?.automaticArticleSubheadingBehavior
-            ?? context.options?.automaticArticleSubheadingBehavior
-        {
-            shouldCreateAutomaticArticleSubheading = !(automaticSubheadingOption == .disabled)
-        } else {
-            shouldCreateAutomaticArticleSubheading = true
-        }
-        
-        return shouldCreateAutomaticArticleSubheading
+        return node.options?.automaticArticleSubheadingEnabled
+            ?? context.options?.automaticArticleSubheadingEnabled
+            ?? true
     }
 
     private func topicsSectionStyle(for node: DocumentationNode) -> RenderNode.TopicsSectionStyle {

Sources/SwiftDocC/Semantics/Options/AutomaticArticleSubheading.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2022-2023 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -19,22 +19,29 @@ import Markdown
 public class AutomaticArticleSubheading: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
-    /// The specified behavior for automatic subheading generation.
+    // This property exist so that the generated directive documentation makes it
+    // clear that "enabled" and "disabled" are then two possible values.
+    
+    /// Whether or not DocC generates automatic second-level "Overview" subheadings.
     @DirectiveArgumentWrapped(name: .unnamed)
-    public private(set) var behavior: Behavior
+    public private(set) var enabledness: Enabledness
 
-    /// A behavior for automatic subheading generation.
-    public enum Behavior: String, CaseIterable, DirectiveArgumentValueConvertible {
-        /// No subheading should be created for the article.
-        case disabled
-        
-        /// An overview subheading should be created containing the article's
-        /// first paragraph of content.
+    /// A value that represent whether automatic subheading generation is enabled or disabled.
+    public enum Enabledness: String, CaseIterable, DirectiveArgumentValueConvertible {
+        /// An overview subheading should be automatically created for the article (the default).
         case enabled
+        
+        /// No automatic overview subheading should be created for the article.
+        case disabled
+    }
+    
+    /// Whether or not DocC generates automatic second-level "Overview" subheadings.
+    public var enabled: Bool {
+        return enabledness == .enabled
     }
 
     static var keyPaths: [String : AnyKeyPath] = [
-        "behavior"  : \AutomaticArticleSubheading._behavior,
+        "enabledness"  : \AutomaticArticleSubheading._enabledness,
     ]
 
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")

Sources/SwiftDocC/Semantics/Options/AutomaticSeeAlso.swift

@@ -16,21 +16,29 @@ import Markdown
 public class AutomaticSeeAlso: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
-    /// The specified behavior for automatic See Also section generation.
+    // This property exist so that the generated directive documentation makes it
+    // clear that "enabled" and "disabled" are then two possible values.
+    
+    /// Whether or not DocC generates automatic See Also sections.
     @DirectiveArgumentWrapped(name: .unnamed)
-    public private(set) var behavior: Behavior
+    public private(set) var enabledness: Enabledness
 
-    /// A behavior for automatic See Also section generation.
-    public enum Behavior: String, CaseIterable, DirectiveArgumentValueConvertible {
-        /// A See Also section will not be automatically created.
-        case disabled
+    /// A value that represent whether automatic See Also section generation is enabled or disabled.
+    public enum Enabledness: String, CaseIterable, DirectiveArgumentValueConvertible {
+        /// A See Also section should be automatically created (the default).
+        case enabled
 
-        /// A See Also section will be automatically created based on the page's siblings.
-        case siblingPages
+        /// No automatic See Also section should be created.
+        case disabled
+    }
+    
+    /// Whether or not DocC generates automatic See Also sections.
+    public var enabled: Bool {
+        return enabledness == .enabled
     }
 
     static var keyPaths: [String : AnyKeyPath] = [
-        "behavior"  : \AutomaticSeeAlso._behavior,
+        "enabledness"  : \AutomaticSeeAlso._enabledness,
     ]
 
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")

Sources/SwiftDocC/Semantics/Options/AutomaticTitleHeading.swift

@@ -18,21 +18,29 @@ import Markdown
 public class AutomaticTitleHeading: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
-    /// The specified behavior for automatic title heading generation.
+    // This property exist so that the generated directive documentation makes it
+    // clear that "enabled" and "disabled" are then two possible values.
+    
+    /// Whether or not DocC generates automatic title headings.
     @DirectiveArgumentWrapped(name: .unnamed)
-    public private(set) var behavior: Behavior
+    public private(set) var enabledness: Enabledness
 
-    /// A behavior for automatic title heading generation.
-    public enum Behavior: String, CaseIterable, DirectiveArgumentValueConvertible {
-        /// No title heading should be created for the page.
-        case disabled
+    /// A value that represent 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
 
-        /// A title heading based on the page's kind should be automatically created.
-        case pageKind
+        /// No automatic title heading should be created for the page.
+        case disabled
+    }
+    
+    /// Whether or not DocC generates automatic title headings.
+    public var enabled: Bool {
+        return enabledness == .enabled
     }
 
     static var keyPaths: [String : AnyKeyPath] = [
-        "behavior"  : \AutomaticTitleHeading._behavior,
+        "enabledness"  : \AutomaticTitleHeading._enabledness,
     ]
 
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")

Sources/SwiftDocC/Semantics/Options/Options.swift

@@ -44,19 +44,19 @@ public class Options: Semantic, AutomaticDirectiveConvertible {
     @ChildDirective
     public private(set) var _topicsVisualStyle: TopicsVisualStyle? = nil
 
-    /// If given, the authored behavior for automatic See Also section generation.
-    public var automaticSeeAlsoBehavior: AutomaticSeeAlso.Behavior? {
-        return _automaticSeeAlso?.behavior
+    /// If given, whether or not automatic See Also section generation is enabled.
+    public var automaticSeeAlsoEnabled: Bool? {
+        return _automaticSeeAlso?.enabled
     }
 
-    /// If given, the authored behavior for automatic Title Heading generation.
-    public var automaticTitleHeadingBehavior: AutomaticTitleHeading.Behavior? {
-        return _automaticTitleHeading?.behavior
+    /// If given, whether or not automatic Title Heading generation is enabled.
+    public var automaticTitleHeadingEnabled: Bool? {
+        return _automaticTitleHeading?.enabled
     }
 
-    /// If given, the authored behavior for automatic article subheading generation.
-    public var automaticArticleSubheadingBehavior: AutomaticArticleSubheading.Behavior? {
-        return _automaticArticleSubheading?.behavior
+    /// If given, whether or not automatic article subheading generation is enabled.
+    public var automaticArticleSubheadingEnabled: Bool? {
+        return _automaticArticleSubheading?.enabled
     }
 
     /// If given, the authored style for a page's Topics section.