update JSON structure for extensibility

Author: Jesse Haigh

Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift

@@ -63,7 +63,9 @@ internal struct InvalidCodeBlockOption: Checker {
             // code property ends in a newline. this gives us a bogus extra line.
             let lineCount: Int = codeBlock.code.split(omittingEmptySubsequences: false, whereSeparator: { $0.isNewline }).count - 1
 
-            guard let indices = RenderBlockContent.CodeBlockOptions.parseCodeBlockOptionsArray(value) else {
+            let indices = RenderBlockContent.CodeBlockOptions.parseCodeBlockOptionsArray(value)
+
+            if !value.isEmpty, indices.isEmpty {
                 let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Could not parse \(token.rawValue.singleQuoted) indices from \(value.singleQuoted). Expected an integer (e.g. 3) or an array (e.g. [1, 3, 5])")
                 problems.append(Problem(diagnostic: diagnostic, possibleSolutions: []))
                 return

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

@@ -139,10 +139,24 @@ public enum RenderBlockContent: Equatable {
     public struct CodeBlockOptions: Equatable {
         public var language: String?
         public var copyToClipboard: Bool
-        public var wrap: Int
-        public var highlight: [Int]
         public var showLineNumbers: Bool
-        public var strikeout: [Int]
+        public var wrap: Int
+        public var lineAnnotations: [LineAnnotation]
+
+        public struct Position: Equatable, Codable {
+            var line: Int
+            var character: Int?
+        }
+
+        public struct Range: Equatable, Codable {
+            var start: Position
+            var end: Position
+        }
+
+        public struct LineAnnotation: Equatable, Codable {
+            var style: String
+            var range: Range
+        }
 
         public enum OptionName: String, CaseIterable {
             case _nonFrozenEnum_useDefaultCase
@@ -166,10 +180,9 @@ public enum RenderBlockContent: Equatable {
         public init() {
             self.language = ""
             self.copyToClipboard = true
-            self.wrap = 0
-            self.highlight = []
             self.showLineNumbers = false
-            self.strikeout = []
+            self.wrap = 0
+            self.lineAnnotations = []
         }
 
         public init(parsingLanguageString language: String?) {
@@ -186,27 +199,53 @@ public enum RenderBlockContent: Equatable {
                 self.wrap = 0
             }
 
-            if let highlightString = tokens.first(where: { $0.name == .highlight })?.value,
-               let highlightValue = Self.parseCodeBlockOptionsArray(highlightString) {
-                self.highlight = highlightValue
-            } else {
-                self.highlight = []
+            var annotations: [LineAnnotation] = []
+
+            if let highlightString = tokens.first(where: { $0.name == .highlight })?.value {
+                let highlightValue = Self.parseCodeBlockOptionsArray(highlightString)
+                for line in highlightValue {
+                    let pos = Position(line: line, character: nil)
+                    let range = Range(start: pos, end: pos)
+                    annotations.append(LineAnnotation(style: "highlight", range: range))
+                }
             }
 
-            if let strikeoutString = tokens.first(where: { $0.name == .strikeout })?.value,
-               let strikeoutValue = Self.parseCodeBlockOptionsArray(strikeoutString) {
-                self.strikeout = strikeoutValue
-            } else {
-                self.strikeout = []
+            if let strikeoutString = tokens.first(where: { $0.name == .strikeout })?.value {
+                let strikeoutValue = Self.parseCodeBlockOptionsArray(strikeoutString)
+                for line in strikeoutValue {
+                    let pos = Position(line: line, character: nil)
+                    let range = Range(start: pos, end: pos)
+                    annotations.append(LineAnnotation(style: "strikeout", range: range))
+                }
             }
+
+            self.lineAnnotations = annotations
         }
 
-        public init(copyToClipboard: Bool, wrap: Int, highlight: [Int], strikeout: [Int], showLineNumbers: Bool) {
+        public init(copyToClipboard: Bool, showLineNumbers: Bool, wrap: Int, highlight: [Int], strikeout: [Int]) {
             self.copyToClipboard = copyToClipboard
+            self.showLineNumbers = showLineNumbers
             self.wrap = wrap
-            self.highlight = highlight
+
+            var annotations: [LineAnnotation] = []
+            for line in highlight {
+                    let pos = Position(line: line, character: nil)
+                    let range = Range(start: pos, end: pos)
+                    annotations.append(LineAnnotation(style: "highlight", range: range))
+            }
+            for line in strikeout {
+                    let pos = Position(line: line, character: nil)
+                    let range = Range(start: pos, end: pos)
+                    annotations.append(LineAnnotation(style: "strikeout", range: range))
+            }
+            self.lineAnnotations = annotations
+        }
+
+        public init(copyToClipboard: Bool, showLineNumbers: Bool, wrap: Int, lineAnnotations: [LineAnnotation]) {
+            self.copyToClipboard = copyToClipboard
             self.showLineNumbers = showLineNumbers
-            self.strikeout = strikeout
+            self.wrap = wrap
+            self.lineAnnotations = lineAnnotations
         }
 
         /// A function that parses array values on code block options from the language line string
@@ -863,7 +902,7 @@ extension RenderBlockContent.Table: Codable {
 extension RenderBlockContent: Codable {
     private enum CodingKeys: CodingKey {
         case type
-        case inlineContent, content, caption, style, name, syntax, code, level, text, items, media, runtimePreview, anchor, summary, example, metadata, start, copyToClipboard, wrap, highlight, strikeout, showLineNumbers
+        case inlineContent, content, caption, style, name, syntax, code, level, text, items, media, runtimePreview, anchor, summary, example, metadata, start, copyToClipboard, showLineNumbers, wrap, lineAnnotations
         case request, response
         case header, rows
         case numberOfColumns, columns
@@ -887,13 +926,12 @@ extension RenderBlockContent: Codable {
         case .codeListing:
             let copy = FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled
             let options: CodeBlockOptions?
-            if !Set(container.allKeys).isDisjoint(with: [.copyToClipboard, .wrap, .highlight, .strikeout, .showLineNumbers]) {
+            if !Set(container.allKeys).isDisjoint(with: [.copyToClipboard, .showLineNumbers, .wrap, .lineAnnotations]) {
                 options = try CodeBlockOptions(
                     copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? copy,
+                    showLineNumbers: container.decodeIfPresent(Bool.self, forKey: .showLineNumbers) ?? false,
                     wrap: container.decodeIfPresent(Int.self, forKey: .wrap) ?? 0,
-                    highlight: container.decodeIfPresent([Int].self, forKey: .highlight) ?? [],
-                    strikeout: container.decodeIfPresent([Int].self, forKey: .strikeout) ?? [],
-                    showLineNumbers: container.decodeIfPresent(Bool.self, forKey: .showLineNumbers) ?? false
+                    lineAnnotations: container.decodeIfPresent([CodeBlockOptions.LineAnnotation].self, forKey: .lineAnnotations) ?? []
                 )
             } else {
                 options = nil
@@ -1007,10 +1045,9 @@ extension RenderBlockContent: Codable {
             try container.encode(l.code, forKey: .code)
             try container.encodeIfPresent(l.metadata, forKey: .metadata)
             try container.encodeIfPresent(l.options?.copyToClipboard, forKey: .copyToClipboard)
-            try container.encodeIfPresent(l.options?.wrap, forKey: .wrap)
-            try container.encodeIfPresent(l.options?.highlight, forKey: .highlight)
-            try container.encodeIfPresent(l.options?.strikeout, forKey: .strikeout)
             try container.encodeIfPresent(l.options?.showLineNumbers, forKey: .showLineNumbers)
+            try container.encodeIfPresent(l.options?.wrap, forKey: .wrap)
+            try container.encodeIfPresent(l.options?.lineAnnotations, forKey: .lineAnnotations)
         case .heading(let h):
             try container.encode(h.level, forKey: .level)
             try container.encode(h.text, forKey: .text)

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json

@@ -781,6 +781,43 @@
                     }
                 }
             },
+            "LineAnnotation": {
+                "type": "object",
+                "properties": {
+                    "style": {
+                        "type": "string",
+                        "enum": ["highlight", "strikeout"]
+                    },
+                    "range": {
+                        "$ref": "#/components/schemas/CharacterRange"
+                    }
+                }
+            },
+            "CharacterRange": {
+                "type": "object",
+                "properties": {
+                    "start": {
+                        "$ref": "#/components/schemas/Position"
+                    },
+                    "end": {
+                        "$ref": "#/components/schemas/Position"
+                    }
+                }
+            },
+            "Position": {
+                "type": "object",
+                "properties": {
+                    "line": {
+                        "type": "integer"
+                    },
+                    "character": {
+                        "type": "integer"
+                    }
+                },
+                "required": [
+                    "line"
+                ]
+            },
             "CodeListing": {
                 "type": "object",
                 "required": [
@@ -815,16 +852,10 @@
                     "wrap": {
                         "type": "integer"
                     },
-                    "highlight": {
-                        "type": "array",
-                        "items": {
-                            "type": "integer"
-                        }
-                    },
-                    "strikeout": {
+                    "lineAnnotations": {
                         "type": "array",
                         "items": {
-                            "type": "integer"
+                            "$ref": "#/components/schemas/LineAnnotation"
                         }
                     }
                 }