Document the default behavior of the DocumentationExtension directive (#833)

* Document DocumentationExtension directive's default behavior

rdar://79096832

* Raise a warning for redundant DocumentationExtension configuration

* Increase severity to 'warning' so that its emitted by default

* Fix test that was asserting "append" behavior

Author: d-ronnqvist

Sources/SwiftDocC/Semantics/Metadata/DocumentationExtension.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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
@@ -11,26 +11,28 @@
 import Foundation
 import Markdown
 
-/// A directive that controls how the documentation-extension file merges with or overrides the in-source documentation.
+/// Defines whether the content in a documentation extension file amends or replaces in-source documentation.
 ///
-/// When the ``behavior`` property is ``Behavior/append``, the content from the documentation-extension file is added after the content from
-/// the in-source documentation for that symbol.
-/// If a documentation-extension file doesn't have a `DocumentationExtension` directive, then it has the ``Behavior/append`` behavior.
+/// By default, content from the documentation-extension file is added after the content from the in-source documentation for that symbol.
 ///
-/// When the ``behavior`` property is ``Behavior/override``, the content from the documentation-extension file completely replaces the content
-/// from the in-source documentation for that symbol
+/// You get this default behavior in two cases:
+/// - when the documentation-extension file doesn't have a `DocumentationExtension` directive
+/// - when the `DocumentationExtension` directive explicitly specifies the ``Behavior/append`` behavior
+///
+/// The other merge behavior completely replaces the content from the in-source documentation for that symbol with the content from the documentation-extension file. To get this behavior, specify ``Behavior/override`` as the merge behavior.
 ///
-/// This directive is only valid within a ``Metadata`` directive:
 /// ```
 /// @Metadata {
 ///    @DocumentationExtension(mergeBehavior: override)
 /// }
 /// ```
+///
+/// The `DocumentationExtension` is only valid within a ``Metadata`` directive.
 public final class DocumentationExtension: Semantic, AutomaticDirectiveConvertible {
     public static let introducedVersion = "5.5"
     public let originalMarkup: BlockDirective
 
-    /// The merge behavior for this documentation extension.
+    /// A value of `append` or `override`, denoting whether an extension file's content amends or replaces the in-source documentation.
     @DirectiveArgumentWrapped(name: .custom("mergeBehavior"))
     public var behavior: Behavior
 
@@ -47,6 +49,25 @@ public final class DocumentationExtension: Semantic, AutomaticDirectiveConvertib
         case override
     }
 
+    func validate(source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> Bool {
+        if behavior == .append {
+            let diagnostic = Diagnostic(
+                source: source,
+                severity: .warning,
+                range: originalMarkup.range,
+                identifier: "org.swift.docc.\(Self.directiveName).NoConfiguration",
+                summary: "\(Self.directiveName.singleQuoted) doesn't change default configuration and has no effect"
+            )
+            
+            let solutions = originalMarkup.range.map {
+                [Solution(summary: "Remove this \(Self.directiveName.singleQuoted) directive.", replacements: [Replacement(range: $0, replacement: "")])]
+            } ?? []
+            problems.append(Problem(diagnostic: diagnostic, possibleSolutions: solutions))
+        }
+        
+        return true
+    }
+    
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
     init(originalMarkup: BlockDirective) {
         self.originalMarkup = originalMarkup

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/DocumentationExtension.md

@@ -1,36 +1,35 @@
-# ``docc/DocumentationExtension``
+# ``DocumentationExtension``
 
-Defines whether the content in a documentation extension file amends or replaces in-source documentation.
+Defines whether the content in a documentation extension file replaces in-source documentation or amends it (the default).
 
 @Metadata {
     @DocumentationExtension(mergeBehavior: override)
 }
 
 - Parameters:
-    - mergeBehavior: A value of `append` or `override`, denoting whether an extension file's content amends or replaces the in-source documentation. **(required)**
+    - mergeBehavior: A value of `override` to replace the in-source documentation with the extension file's content. **(required)**
 
 ## Overview
 
+By default, content from the documentation-extension file is added after the content from the in-source documentation for that symbol.
+
 Swift framework and package APIs are typically documented using comments that reside in-source, alongside the APIs themselves. In some cases, you may wish to supplement or replace in-source documentation with content from dedicated documentation extension files. To learn about this process, see <doc:adding-supplemental-content-to-a-documentation-catalog>.
 
 Place the `DocumentationExtension` directive within a `Metadata` directive in a documentation extension file. Set the `mergeBehavior` parameter to `append` or `override` to indicate whether the extension file's content amends or replaces the in-source documentation.
 
 ```
-# ``SlothCreator/Sloth``
-
 @Metadata {
-    @DocumentationExtension(mergeBehavior: append)
+    @DocumentationExtension(mergeBehavior: override)
 }
+```
 
-## Sleeping Habits
-
-Sloths sleep in trees by curling into a ball and hanging by their claws.
-````
+> Note:
+> You can specify a `append` merge behavior but it has the same effect as not defining a `@DocumentationExtension` and results in a warning.
 
 ### Containing Elements
 
 The following items can include a documentation extension element:
 
 - ``Metadata``
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md

@@ -8,15 +8,17 @@ Use metadata directives to instruct DocC how to build certain documentation file
 
 ## Overview
 
-Use the `Metadata` directive with other directives to configure how certain documentation files build. Place the directive after the documentation page's title. Use it with the ``DocumentationExtension`` directive to indicate whether content in a documentation extension file amends or replaces in-source documentation.
+Use the `Metadata` directive with other directives to configure how certain documentation files build. Place the directive after the documentation page's title. 
+
+Use it with the ``DocumentationExtension`` directive to replace in-source documentation with the documentation extension file's content. 
 
 ```
 # ``SlothCreator/Sloth``
 
 @Metadata {
-    @DocumentationExtension(mergeBehavior: append)
+    @DocumentationExtension(mergeBehavior: override)
 }
-````
+```
 
 Use the `Metadata` directive with the ``TechnologyRoot`` directive to configure a documentation page that's not associated with a particular framework, so that page appears as a top-level page.
 
@@ -88,4 +90,4 @@ previous versions, @Redirected must be used as a top level directive.
 > Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In
 previous versions, @Redirected must be used as a top level directive.
 
-<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/adding-supplemental-content-to-a-documentation-catalog.md

@@ -60,7 +60,7 @@ Create a sloth and assign personality traits and abilities.
 Sloths are complex creatures that require careful creation and a suitable
 habitat.
 ...
-````
+```
 
 To add an article to your documentation catalog, use a text editor and create a file with an appropriate title and add a `.md` extension.
 
@@ -82,62 +82,35 @@ about organizing your project's documentation, see
 
 ### Add Extension Files to Append to or Override Source Documentation Comments
 
-Although writing documentation comments in source files has many benefits, in some
-circumstances it makes more sense to separate the content from the source
-files, such as:
+Although writing documentation comments in source files has many benefits, in some circumstances it makes more sense to separate content from the source files, such as:
 
 * When you include thorough code listings or numerous images that increase the
   size of your documentation and make source files difficult to manage
 * When your source documentation comments focus on the implementation of your
   code, and aren't appropriate for external documentation
 
-In cases like these, DocC supports supplementing or completely replacing source
-documentation comments with content in extension files. To add an extension file to your
-documentation catalog, create a file within the documentation catalog, then modify the first line of the file to identify the symbol that the file relates to.
+To add an extension file to your documentation catalog, create a file within the documentation catalog, then modify the first line of the file to identify the symbol that the file relates to using a symbol link in a level 1 header. 
+For more information on linking to symbols, see <doc:linking-to-symbols-and-other-content>.
 
-> Important: The symbol path for the page title of an extension file need to start
-with the name of a top-level symbol or the name of the framework.
+> Important: The symbol path for the page title of an extension file need to start with the name of a top-level symbol or the name of the framework.
 
-If the symbol already has source documentation comments, add a
-`DocumentationExtension` directive to specify whether the content of the
-extension file appends to or overrides the source documentation comments. Add
-the `DocumentationExtension` after the first line of the file that specifies
-the symbol, using the following format:
-
-````markdown
-@Metadata {
-    @DocumentationExtension(mergeBehavior: [append or override])
-}
-````
-
-The `mergeBehavior` parameter determines whether DocC adds the extension file's
-content to the bottom of the source documentation comments, or replaces
-the source documentation comments entirely.
-
-To add the extension file's content to source documentation comments, use
-`append` for the `mergeBehavior`. For example, to add a section
-about the sleeping habits of sloths to the `Sloth` type, the extension file
-contains the following:
+By default, the extension file's content adds to the symbol's existing source documentation comment. 
+You can leave key information in the documentation comment---where it's available to people reading the source code---and use the extension file for longer documentation, code examples, images, and for organizing you documentation hierarchy. 
+For example, to add a section about the sleeping habits of sloths to the `Sloth` type, the extension file contains the following:
 
 ```markdown
-# ``SlothCreator/Sloth``
-
-@Metadata {
-    @DocumentationExtension(mergeBehavior: append)
-}
+# ``Sloth``
 
 ## Sleeping Habits
 
 Sloths sleep in trees by curling into a ball and hanging by their claws.
-````
+```
 
-Alternatively, to completely replace the source documentation comments, use
-`override`. In this case, you add content after the directive that DocC uses
-when generating documentation. For example, to replace the source documentation
-comments of the `Sloth` type in SlothCreator, the extension file contains the following:
+If the symbol's existing source documentation focuses on implementation and isn't appropriate for external documentation, you can completely replace the documentation comment's content with the extension file's content by adding a ``DocumentationExtension`` directive. 
+For example, to replace the source documentation comments of the `Sloth` type in SlothCreator, the extension file contains the following:
 
 ```markdown
-# ``SlothCreator/Sloth``
+# ``Sloth``
 
 @Metadata {
     @DocumentationExtension(mergeBehavior: override)
@@ -148,9 +121,9 @@ This overrides the in-source summary.
 ## Overview
 
 This content overrides in-source content.
-````
+```
 
 For more information on `Metadata` and other directives, see
 <doc:Metadata>.
 
-<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Semantics/DocumentationExtensionTests.swift

@@ -36,7 +36,8 @@ class DocumentationExtensionTests: XCTestCase {
         var problems = [Problem]()
         let options = DocumentationExtension(from: directive, source: nil, for: bundle, in: context, problems: &problems)
         XCTAssertNotNil(options)
-        XCTAssertTrue(problems.isEmpty)
+        XCTAssertEqual(problems.count, 1)
+        XCTAssertEqual("org.swift.docc.DocumentationExtension.NoConfiguration", problems.first?.diagnostic.identifier)
         XCTAssertEqual(options?.behavior, .append)
     }
 
@@ -66,7 +67,7 @@ class DocumentationExtensionTests: XCTestCase {
     }
 
     func testExtraArguments() throws {
-        let source = "@DocumentationExtension(mergeBehavior: append, argument: value)"
+        let source = "@DocumentationExtension(mergeBehavior: override, argument: value)"
         let document = Document(parsing: source, options: .parseBlockDirectives)
         let directive = document.child(at: 0)! as! BlockDirective
         let (bundle, context) = try testBundleAndContext(named: "TestBundle")

Tests/SwiftDocCTests/Semantics/MetadataTests.swift

@@ -83,7 +83,7 @@ class MetadataTests: XCTestCase {
     func testDocumentationExtensionSupport() throws {
         let source = """
         @Metadata {
-           @DocumentationExtension(mergeBehavior: append)
+           @DocumentationExtension(mergeBehavior: override)
         }
         """
         let document = Document(parsing: source, options: .parseBlockDirectives)
@@ -93,7 +93,7 @@ class MetadataTests: XCTestCase {
         let metadata = Metadata(from: directive, source: nil, for: bundle, in: context, problems: &problems)
         XCTAssertNotNil(metadata)
         XCTAssertEqual(0, problems.count)
-        XCTAssertEqual(metadata?.documentationOptions?.behavior, .append)
+        XCTAssertEqual(metadata?.documentationOptions?.behavior, .override)
     }
 
     func testRepeatDocumentationExtension() throws {
@@ -109,8 +109,11 @@ class MetadataTests: XCTestCase {
         var problems = [Problem]()
         let metadata = Metadata(from: directive, source: nil, for: bundle, in: context, problems: &problems)
         XCTAssertNotNil(metadata)
-        XCTAssertEqual(1, problems.count)
-        XCTAssertEqual("org.swift.docc.HasAtMostOne<Metadata, DocumentationExtension>.DuplicateChildren", problems.first?.diagnostic.identifier)
+        XCTAssertEqual(2, problems.count)
+        XCTAssertEqual(problems.map(\.diagnostic.identifier).sorted(), [
+            "org.swift.docc.DocumentationExtension.NoConfiguration",
+            "org.swift.docc.HasAtMostOne<Metadata, DocumentationExtension>.DuplicateChildren",
+        ])
         XCTAssertEqual(metadata?.documentationOptions?.behavior, .append)
     }
 

Tests/SwiftDocCTests/Semantics/SymbolTests.swift

@@ -150,10 +150,6 @@ class SymbolTests: XCTestCase {
                 """,
             articleContent: """
                 # Leading heading is ignored
-                
-                @Metadata {
-                   @DocumentationExtension(mergeBehavior: append)
-                }
                 """
         )
         XCTAssert(problems.isEmpty)