add feature flag 'enable-experimental-code-block' for copy-to-clipboard and other code block annotations

Jesse Haigh · Jesse Haigh · commit 3ae43b146b66 · 2025-08-11T15:30:50.000-06:00
diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift b/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift
@@ -2650,7 +2650,6 @@ public class DocumentationContext {
             }
         }
     }
-    
     /// A closure type getting the information about a reference in a context and returns any possible problems with it.
     public typealias ReferenceCheck = (DocumentationContext, ResolvedTopicReference) -> [Problem]
     
diff --git a/Sources/SwiftDocC/Infrastructure/Workspace/FeatureFlags+Info.swift b/Sources/SwiftDocC/Infrastructure/Workspace/FeatureFlags+Info.swift
@@ -37,11 +37,20 @@ extension DocumentationBundle.Info {
             self.unknownFeatureFlags = []
         }
 
+        /// This feature flag corresponds to ``FeatureFlags/isExperimentalCodeBlockEnabled``.
+        public var experimentalCodeBlock: Bool?
+
+        public init(experimentalCodeBlock: Bool? = nil) {
+            self.experimentalCodeBlock = experimentalCodeBlock
+            self.unknownFeatureFlags = []
+        }
+
         /// A list of decoded feature flag keys that didn't match a known feature flag.
         public let unknownFeatureFlags: [String]
 
         enum CodingKeys: String, CodingKey, CaseIterable {
             case experimentalOverloadedSymbolPresentation = "ExperimentalOverloadedSymbolPresentation"
+            case experimentalCodeBlock = "ExperimentalCodeBlock"
         }
 
         struct AnyCodingKeys: CodingKey {
@@ -66,6 +75,9 @@ extension DocumentationBundle.Info {
                     switch codingKey {
                     case .experimentalOverloadedSymbolPresentation:
                         self.experimentalOverloadedSymbolPresentation = try values.decode(Bool.self, forKey: flagName)
+
+                    case .experimentalCodeBlock:
+                        self.experimentalCodeBlock = try values.decode(Bool.self, forKey: flagName)
                     }
                 } else {
                     unknownFeatureFlags.append(flagName.stringValue)
@@ -79,6 +91,7 @@ extension DocumentationBundle.Info {
             var container = encoder.container(keyedBy: CodingKeys.self)
 
             try container.encode(experimentalOverloadedSymbolPresentation, forKey: .experimentalOverloadedSymbolPresentation)
+            try container.encode(experimentalCodeBlock, forKey: .experimentalCodeBlock)
         }
     }
 }
diff --git a/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift b/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift
@@ -721,12 +721,16 @@ extension RenderBlockContent: Codable {
             }
             self = try .aside(.init(style: style, content: container.decode([RenderBlockContent].self, forKey: .content)))
         case .codeListing:
+            var copy = false
+            if FeatureFlags.current.isExperimentalCodeBlockEnabled {
+                copy = true
+            }
             self = try .codeListing(.init(
                 syntax: container.decodeIfPresent(String.self, forKey: .syntax),
                 code: container.decode([String].self, forKey: .code),
                 metadata: container.decodeIfPresent(RenderContentMetadata.self, forKey: .metadata),
-                copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? true
-            ))
+                copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? copy
+                ))
         case .heading:
             self = try .heading(.init(level: container.decode(Int.self, forKey: .level), text: container.decode(String.self, forKey: .text), anchor: container.decodeIfPresent(String.self, forKey: .anchor)))
         case .orderedList:
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift b/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift
@@ -47,34 +47,41 @@ struct RenderContentCompiler: MarkupVisitor {
     
     mutating func visitCodeBlock(_ codeBlock: CodeBlock) -> [any RenderContent] {
         // Default to the bundle's code listing syntax if one is not explicitly declared in the code block.
-        struct ParsedOptions {
-            var lang: String?
-            var nocopy = false
-        }
 
-        func parseLanguageString(_ input: String?) -> ParsedOptions {
-            guard let input else { return ParsedOptions() }
+        if FeatureFlags.current.isExperimentalCodeBlockEnabled {
+
+            struct ParsedOptions {
+                var lang: String?
+                var nocopy = false
+            }
+
+            func parseLanguageString(_ input: String?) -> ParsedOptions {
+                guard let input else { return ParsedOptions() }
 
-            let parts = input
+                let parts = input
                     .split(separator: ",")
                     .map { $0.trimmingCharacters(in: .whitespaces) }
 
-            var options = ParsedOptions()
+                var options = ParsedOptions()
 
-            for part in parts {
-                let lower = part.lowercased()
-                if lower == "nocopy" {
-                    options.nocopy = true
-                } else if options.lang == nil {
-                    options.lang = part
+                for part in parts {
+                    let lower = part.lowercased()
+                    if lower == "nocopy" {
+                        options.nocopy = true
+                    } else if options.lang == nil {
+                        options.lang = part
+                    }
                 }
+                return options
             }
-            return options
-        }
 
-        let options = parseLanguageString(codeBlock.language)
+            let options = parseLanguageString(codeBlock.language)
+
+            return [RenderBlockContent.codeListing(.init(syntax: options.lang ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: !options.nocopy))]
 
-        return [RenderBlockContent.codeListing(.init(syntax: options.lang ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: !options.nocopy))]
+        } else {
+            return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: false))]
+        }
     }
     
     mutating func visitHeading(_ heading: Heading) -> [any RenderContent] {
diff --git a/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift b/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift
@@ -68,11 +68,19 @@ extension Snippet: RenderableDirectiveConvertible {
                 let lines = snippetMixin.lines[lineRange]
                 let minimumIndentation = lines.map { $0.prefix { $0.isWhitespace }.count }.min() ?? 0
                 let trimmedLines = lines.map { String($0.dropFirst(minimumIndentation)) }
-                return [RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: trimmedLines, metadata: nil, copyToClipboard: true))]
+                var copy = false
+                if FeatureFlags.current.isExperimentalCodeBlockEnabled {
+                    copy = true
+                }
+                return [RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: trimmedLines, metadata: nil, copyToClipboard: copy))]
             } else {
                 // Render the whole snippet with its explanation content.
                 let docCommentContent = snippetEntity.markup.children.flatMap { contentCompiler.visit($0) }
-                let code = RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: snippetMixin.lines, metadata: nil, copyToClipboard: true))
+                var copy = false
+                if FeatureFlags.current.isExperimentalCodeBlockEnabled {
+                    copy = true
+                }
+                let code = RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: snippetMixin.lines, metadata: nil, copyToClipboard: copy))
                 return docCommentContent + [code]
             }
     }
diff --git a/Sources/SwiftDocC/Utility/FeatureFlags.swift b/Sources/SwiftDocC/Utility/FeatureFlags.swift
@@ -13,7 +13,10 @@ public struct FeatureFlags: Codable {
     /// The current feature flags that Swift-DocC uses to conditionally enable
     /// (usually experimental) behavior in Swift-DocC.
     public static var current = FeatureFlags()
-    
+
+    /// Whether or not experimental annotation of code blocks is enabled.
+    public var isExperimentalCodeBlockEnabled = false
+
     /// Whether or not experimental support for device frames on images and video is enabled.
     public var isExperimentalDeviceFrameSupportEnabled = false
 
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
@@ -19,7 +19,7 @@ extension ConvertAction {
     public init(fromConvertCommand convert: Docc.Convert, withFallbackTemplate fallbackTemplateURL: URL? = nil) throws {
         var standardError = LogHandle.standardError
         let outOfProcessResolver: OutOfProcessReferenceResolver?
-        
+        FeatureFlags.current.isExperimentalCodeBlockEnabled = convert.enableExperimentalCodeBlock
         FeatureFlags.current.isExperimentalDeviceFrameSupportEnabled = convert.enableExperimentalDeviceFrameSupport
         FeatureFlags.current.isExperimentalLinkHierarchySerializationEnabled = convert.enableExperimentalLinkHierarchySerialization
         FeatureFlags.current.isExperimentalOverloadedSymbolPresentationEnabled = convert.enableExperimentalOverloadedSymbolPresentation
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
@@ -475,7 +475,13 @@ extension Docc {
         struct FeatureFlagOptions: ParsableArguments {
             @Flag(help: "Allows for custom templates, like `header.html`.")
             var experimentalEnableCustomTemplates = false
-            
+
+            @Flag(
+                name: .customLong("enable-experimental-code-block"),
+                help: "Annotate code blocks with additional metadata to support copy-to-clipboard, highlighting, and wrapping on code blocks."
+            )
+            var enableExperimentalCodeBlock = false
+
             @Flag(help: .hidden)
             var enableExperimentalDeviceFrameSupport = false
             
@@ -557,6 +563,14 @@ extension Docc {
             
         }
 
+        /// A user-provided value that is true if the user enables experimental support for code block annotation.
+        ///
+        /// Defaults to false.
+        public var enableExperimentalCodeBlock: Bool {
+            get { featureFlags.enableExperimentalCodeBlock }
+            set { featureFlags.enableExperimentalCodeBlock = newValue}
+        }
+
         /// A user-provided value that is true if the user enables experimental support for device frames.
         ///
         /// Defaults to false.
diff --git a/Tests/SwiftDocCTests/Model/RenderContentMetadataTests.swift b/Tests/SwiftDocCTests/Model/RenderContentMetadataTests.swift
@@ -54,7 +54,7 @@ class RenderContentMetadataTests: XCTestCase {
             RenderInlineContent.text("Content"),
         ])
         
-        let code = RenderBlockContent.codeListing(.init(syntax: nil, code: [], metadata: metadata, copyToClipboard: true))
+        let code = RenderBlockContent.codeListing(.init(syntax: nil, code: [], metadata: metadata, copyToClipboard: false))
         let data = try JSONEncoder().encode(code)
         let roundtrip = try JSONDecoder().decode(RenderBlockContent.self, from: data)
         
diff --git a/Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift b/Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift
@@ -44,7 +44,7 @@ class RenderNodeSerializationTests: XCTestCase {
                     .strong(inlineContent: [.text("Project > Run")]),
                     .text(" menu item, or the following code:"),
                 ])),
-                .codeListing(.init(syntax: "swift", code: ["xcrun xcodebuild -h", "xcrun xcodebuild build -configuration Debug"], metadata: nil, copyToClipboard: true)),
+                .codeListing(.init(syntax: "swift", code: ["xcrun xcodebuild -h", "xcrun xcodebuild build -configuration Debug"], metadata: nil, copyToClipboard: false)),
             ]))
         ]
         
@@ -71,16 +71,16 @@ class RenderNodeSerializationTests: XCTestCase {
         let assessment1 = TutorialAssessmentsRenderSection.Assessment(title: [.paragraph(.init(inlineContent: [.text("Lorem ipsum dolor sit amet?")]))],
                                                                      content: nil,
                                                                      choices: [
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["override func viewDidLoad() {", "super.viewDidLoad()", "}"], metadata: nil, copyToClipboard: true))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "That's right!"),
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: true))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Not quite."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["override func viewDidLoad() {", "super.viewDidLoad()", "}"], metadata: nil, copyToClipboard: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "That's right!"),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: false))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Not quite."),
             .init(content: [.paragraph(.init(inlineContent: [.text("None of the above.")]))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: nil),
         ])
         
         let assessment2 = TutorialAssessmentsRenderSection.Assessment(title: [.paragraph(.init(inlineContent: [.text("Duis aute irure dolor in reprehenderit?")]))],
                                                                      content: [.paragraph(.init(inlineContent: [.text("What is the airspeed velocity of an unladen swallow?")]))],
                                                                      choices: [
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["super.viewWillAppear()"], metadata: nil, copyToClipboard: true))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Correct."),
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: true))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Yep."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["super.viewWillAppear()"], metadata: nil, copyToClipboard: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Correct."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Yep."),
             .init(content: [.paragraph(.init(inlineContent: [.text("None of the above.")]))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Close!"),
         ])
         
diff --git a/Tests/SwiftDocCTests/Rendering/RenderContentCompilerTests.swift b/Tests/SwiftDocCTests/Rendering/RenderContentCompilerTests.swift
@@ -225,6 +225,8 @@ class RenderContentCompilerTests: XCTestCase {
     }
 
     func testCopyToClipboard() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockEnabled)
+
         let (bundle, context) = try await testBundleAndContext()
         var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
 
@@ -247,6 +249,8 @@ class RenderContentCompilerTests: XCTestCase {
     }
 
     func testNoCopyToClipboard() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockEnabled)
+
         let (bundle, context) = try await testBundleAndContext()
         var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
 
diff --git a/Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift b/Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift
@@ -514,7 +514,7 @@ class ListItemExtractorTests: XCTestCase {
             // ```
             // Inner code block
             // ```
-            .codeListing(.init(syntax: nil, code: ["Inner code block"], metadata: nil, copyToClipboard: true)),
+            .codeListing(.init(syntax: nil, code: ["Inner code block"], metadata: nil, copyToClipboard: false)),
 
             // > Warning: Inner aside, with ``ThirdNotFoundSymbol`` link
             .aside(.init(style: .init(asideKind: .warning), content: [
diff --git a/features.json b/features.json
@@ -1,5 +1,8 @@
 {
   "features": [
+    {
+      "name": "code-blocks"
+    },
     {
       "name": "diagnostics-file"
     },

Original file line number	Diff line number	Diff line change
`@@ -2650,7 +2650,6 @@ public class DocumentationContext {`
`2650`	`2650`	`}`
`2651`	`2651`	`}`
`2652`	`2652`	`}`
`2653`		`-`
`2654`	`2653`	`/// A closure type getting the information about a reference in a context and returns any possible problems with it.`
`2655`	`2654`	`public typealias ReferenceCheck = (DocumentationContext, ResolvedTopicReference) -> [Problem]`
`2656`	`2655`
Original file line number	Diff line number	Diff line change
`@@ -37,11 +37,20 @@ extension DocumentationBundle.Info {`
`37`	`37`	`self.unknownFeatureFlags = []`
`38`	`38`	`}`
`39`	`39`
	`40`	+ /// This feature flag corresponds to ``FeatureFlags/isExperimentalCodeBlockEnabled``.
	`41`	`+ public var experimentalCodeBlock: Bool?`
	`42`	`+`
	`43`	`+ public init(experimentalCodeBlock: Bool? = nil) {`
	`44`	`+ self.experimentalCodeBlock = experimentalCodeBlock`
	`45`	`+ self.unknownFeatureFlags = []`
	`46`	`+ }`
	`47`	`+`
`40`	`48`	`/// A list of decoded feature flag keys that didn't match a known feature flag.`
`41`	`49`	`public let unknownFeatureFlags: [String]`
`42`	`50`
`43`	`51`	`enum CodingKeys: String, CodingKey, CaseIterable {`
`44`	`52`	`case experimentalOverloadedSymbolPresentation = "ExperimentalOverloadedSymbolPresentation"`
	`53`	`+ case experimentalCodeBlock = "ExperimentalCodeBlock"`
`45`	`54`	`}`
`46`	`55`
`47`	`56`	`struct AnyCodingKeys: CodingKey {`
`@@ -66,6 +75,9 @@ extension DocumentationBundle.Info {`
`66`	`75`	`switch codingKey {`
`67`	`76`	`case .experimentalOverloadedSymbolPresentation:`
`68`	`77`	`self.experimentalOverloadedSymbolPresentation = try values.decode(Bool.self, forKey: flagName)`
	`78`	`+`
	`79`	`+ case .experimentalCodeBlock:`
	`80`	`+ self.experimentalCodeBlock = try values.decode(Bool.self, forKey: flagName)`
`69`	`81`	`}`
`70`	`82`	`} else {`
`71`	`83`	`unknownFeatureFlags.append(flagName.stringValue)`
`@@ -79,6 +91,7 @@ extension DocumentationBundle.Info {`
`79`	`91`	`var container = encoder.container(keyedBy: CodingKeys.self)`
`80`	`92`
`81`	`93`	`try container.encode(experimentalOverloadedSymbolPresentation, forKey: .experimentalOverloadedSymbolPresentation)`
	`94`	`+ try container.encode(experimentalCodeBlock, forKey: .experimentalCodeBlock)`
`82`	`95`	`}`
`83`	`96`	`}`
`84`	`97`	`}`