diff --git a/Sources/SwiftDocC/Model/DocumentationNode.swift b/Sources/SwiftDocC/Model/DocumentationNode.swift index a788105d9..4ecebc1ad 100644 --- a/Sources/SwiftDocC/Model/DocumentationNode.swift +++ b/Sources/SwiftDocC/Model/DocumentationNode.swift @@ -447,10 +447,20 @@ public struct DocumentationNode { for: SymbolGraph.Symbol.Location.self )?.url() - for comment in docCommentDirectives { - let range = docCommentMarkup.child(at: comment.indexInParent)?.range + for directive in docCommentDirectives { + let range = docCommentMarkup.child(at: directive.indexInParent)?.range - guard BlockDirective.allKnownDirectiveNames.contains(comment.name) else { + // Only throw warnings for known directive names. + // + // This is important so that we avoid throwing warnings when building + // Objective-C/C documentation that includes doxygen commands. + guard BlockDirective.allKnownDirectiveNames.contains(directive.name) else { + continue + } + + // Renderable directives are processed like any other piece of structured markdown (tables, lists, etc.) + // and so are inherently supported in doc comments. + guard DirectiveIndex.shared.renderableDirectives[directive.name] == nil else { continue } @@ -459,8 +469,8 @@ public struct DocumentationNode { severity: .warning, range: range, identifier: "org.swift.docc.UnsupportedDocCommentDirective", - summary: "Directives are not supported in symbol source documentation", - explanation: "Found \(comment.name.singleQuoted) in \(symbol.absolutePath.singleQuoted)" + summary: "The \(directive.name.singleQuoted) directive is not supported in symbol source documentation", + explanation: "Found \(directive.name.singleQuoted) in \(symbol.absolutePath.singleQuoted)" ) var problem = Problem(diagnostic: diagnostic, possibleSolutions: []) diff --git a/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift b/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift index f47d46a62..fa951d518 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift @@ -346,40 +346,12 @@ struct RenderContentCompiler: MarkupVisitor { } mutating func visitBlockDirective(_ blockDirective: BlockDirective) -> [RenderContent] { - switch blockDirective.name { - case Snippet.directiveName: - guard let snippet = Snippet(from: blockDirective, for: bundle, in: context) else { - return [] - } - - guard let snippetReference = resolveSymbolReference(destination: snippet.path), - let snippetEntity = try? context.entity(with: snippetReference), - let snippetSymbol = snippetEntity.symbol, - let snippetMixin = snippetSymbol.mixins[SymbolGraph.Symbol.Snippet.mixinKey] as? SymbolGraph.Symbol.Snippet else { - return [] - } - - if let requestedSlice = snippet.slice, - let requestedLineRange = snippetMixin.slices[requestedSlice] { - // Render only the slice. - let lineRange = requestedLineRange.lowerBound.. [RenderContent] { diff --git a/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift b/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift index b9f1bafe6..0def9cb9e 100644 --- a/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift +++ b/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift @@ -10,6 +10,7 @@ import Foundation import Markdown +import SymbolKit public final class Snippet: Semantic, AutomaticDirectiveConvertible { public let originalMarkup: BlockDirective @@ -45,3 +46,33 @@ public final class Snippet: Semantic, AutomaticDirectiveConvertible { return true } } + +extension Snippet: RenderableDirectiveConvertible { + func render(with contentCompiler: inout RenderContentCompiler) -> [RenderContent] { + guard let snippet = Snippet(from: originalMarkup, for: contentCompiler.bundle, in: contentCompiler.context) else { + return [] + } + + guard let snippetReference = contentCompiler.resolveSymbolReference(destination: snippet.path), + let snippetEntity = try? contentCompiler.context.entity(with: snippetReference), + let snippetSymbol = snippetEntity.symbol, + let snippetMixin = snippetSymbol.mixins[SymbolGraph.Symbol.Snippet.mixinKey] as? SymbolGraph.Symbol.Snippet else { + return [] + } + + if let requestedSlice = snippet.slice, + let requestedLineRange = snippetMixin.slices[requestedSlice] { + // Render only the slice. + let lineRange = requestedLineRange.lowerBound.. +This is a snippet nested inside a tab navigator. + +@TabNavigator { + @Tab("hi") { + @Row { + @Column { + Hello! + } + + @Column { + Hello there! + } + } + + Hello there. + } + + @Tab("hey") { + Hey there. + + @Small { + Hey but small. + } + + @Snippet(path: "Snippets/Snippets/MySnippet", slice: "middle") {} + } +} + + +