SE-0356: Implement snippet slicing (#338)

Add an optional `slice` argument to the `@Snippet` directive, which
will only render a code listing comprised of the line range of the slice.

Remove snippet groups, as they are no longer used in the current design.

Replace logic that filters snippets and fake modules that hold snippets
to a more generic "is virtual" logic. A virtual symbol, topic, or documentation
node should not have its own page of documentation.

Testing: Moved snippet tests to their own test bundle as it was causing a lot
of thrash with navigator tests.

rdar://95220570

Author: bitjammer

Package.resolved

@@ -73,14 +73,8 @@ public class DocumentationContextConverter {
     ///   - source: The source file for the documentation node.
     /// - Returns: The render node representation of the documentation node.
     public func renderNode(for node: DocumentationNode, at source: URL?) throws -> RenderNode? {
-        switch node.kind {
-        case .module:
-            guard !context.onlyHasSnippetRelatedChildren(for: node.reference) else {
-                return nil
-            }
-        case .snippet, .snippetGroup:
+        guard !node.isVirtual else {
             return nil
-        default: break
         }
 
         var translator = RenderNodeTranslator(

Sources/SwiftDocC/Converter/DocumentationContextConverter.swift

@@ -143,10 +143,18 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     ///
     /// This property is initialized during the registration of a documentation bundle.
     public private(set) var rootModules: [ResolvedTopicReference]!
-    
+        
     /// The topic reference of the root module, if it's the only registered module.
     var soleRootModuleReference: ResolvedTopicReference? {
-        rootModules.count == 1 ? rootModules.first : nil
+        guard rootModules.count > 1 else {
+            return rootModules.first
+        }
+        // There are multiple "root modules" but some may be "virtual".
+        // Removing those may leave only one root module left.
+        let nonVirtualModules = rootModules.filter {
+            topicGraph.nodes[$0]?.isVirtual ?? false
+        }
+        return nonVirtualModules.count == 1 ? nonVirtualModules.first : nil
     }
 
     /// Map of document URLs to topic references.
@@ -993,7 +1001,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         } else {
             source = .external
         }
-        let graphNode = TopicGraph.Node(reference: reference, kind: documentation.kind, source: source, title: symbol.defaultSymbol!.names.title)
+        let graphNode = TopicGraph.Node(reference: reference, kind: documentation.kind, source: source, title: symbol.defaultSymbol!.names.title, isVirtual: module.isVirtual)
 
         return ((reference, symbol.uniqueIdentifier, graphNode, documentation), [])
     }
@@ -1185,7 +1193,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
                             }
                         }
                     }
-
+                    
                     if let rootURL = symbolGraphLoader.mainModuleURL(forModule: moduleName), let rootModule = unifiedSymbolGraph.moduleData[rootURL] {
                         addPreparedSymbolToContext(
                             preparedSymbolData(.init(fromSingleSymbol: moduleSymbol, module: rootModule, isMainGraph: true), reference: moduleReference, module: rootModule, moduleReference: moduleReference, bundle: bundle, fileURL: fileURL)
@@ -1937,15 +1945,6 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         topicGraphGlobalAnalysis()
 
         preResolveModuleNames()
-
-        // Symbol Graph modules whose children are all snippets should not
-        // be presented as a top-level preview page.
-        // First, a package might have a similar but different name to its
-        // primary library. Second, snippets are not automatically curated as
-        // other symbols might be.
-        rootModules.removeAll {
-              onlyHasSnippetRelatedChildren(for: $0)
-        }
     }
 
     /// Given a list of topics that have been automatically curated, checks if a topic has been additionally manually curated
@@ -2330,17 +2329,6 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
         topicGraph.traverseBreadthFirst(from: node, observe)
     }
-
-    /// Returns whether a documentation node only has snippet or snippet group children.
-    func onlyHasSnippetRelatedChildren(for reference: ResolvedTopicReference) -> Bool {
-        let children = children(of: reference)
-        guard !children.isEmpty else {
-            return false
-        }
-        return children
-            .compactMap { $0.kind }
-            .allSatisfy({ $0 == .snippet || $0 == .snippetGroup })
-    }
 
     /**
      Attempt to resolve a ``TopicReference``.
@@ -2447,9 +2435,8 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// The references of all the pages in the topic graph.
     public var knownPages: [ResolvedTopicReference] {
         return topicGraph.nodes.values
-            .filter { $0.kind.isPage &&
-                !externallyResolvedSymbols.contains($0.reference) &&
-                !onlyHasSnippetRelatedChildren(for: $0.reference) }
+            .filter { !$0.isVirtual && $0.kind.isPage &&
+                !externallyResolvedSymbols.contains($0.reference) }
             .map { $0.reference }
     }
 

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -196,7 +196,6 @@ extension AutomaticCuration {
             case .`property`: return "Instance Properties"
             case .`protocol`: return "Protocols"
             case .snippet: return "Snippets"
-            case .snippetGroup: return "Snippet Groups"
             case .`struct`: return "Structures"
             case .`subscript`: return "Subscripts"
             case .`typeMethod`: return "Type Methods"

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

@@ -84,12 +84,16 @@ struct TopicGraph {
         /// If true, the hierarchy path is resolvable.
         let isResolvable: Bool
 
-        init(reference: ResolvedTopicReference, kind: DocumentationNode.Kind, source: ContentLocation, title: String, isResolvable: Bool = true) {
+        /// If true, the topic should not be rendered and exists solely to mark relationships.
+        let isVirtual: Bool
+        
+        init(reference: ResolvedTopicReference, kind: DocumentationNode.Kind, source: ContentLocation, title: String, isResolvable: Bool = true, isVirtual: Bool = false) {
             self.reference = reference
             self.kind = kind
             self.source = source
             self.title = title
             self.isResolvable = isResolvable
+            self.isVirtual = isVirtual
         }
 
         func withReference(_ reference: ResolvedTopicReference) -> Node {

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

@@ -58,6 +58,9 @@ public struct DocumentationNode {
 
     /// The unified symbol data that backs this node, if it's backed by a symbol; otherwise `nil`.
     public var unifiedSymbol: UnifiedSymbolGraph.Symbol?
+    
+    /// If true, the node was created implicitly and should not generally be rendered as a page of documentation.
+    public var isVirtual: Bool
 
     /// A discrete unit of documentation
     struct DocumentationChunk {
@@ -122,7 +125,7 @@ public struct DocumentationNode {
     ///   - markup: The markup that makes up the content for the node.
     ///   - semantic: The parsed documentation structure that's described by the documentation content.
     ///   - platformNames: The names of the platforms for which the node is available.
-    public init(reference: ResolvedTopicReference, kind: Kind, sourceLanguage: SourceLanguage, availableSourceLanguages: Set<SourceLanguage>? = nil, name: Name, markup: Markup, semantic: Semantic?, platformNames: Set<String>? = nil) {
+    public init(reference: ResolvedTopicReference, kind: Kind, sourceLanguage: SourceLanguage, availableSourceLanguages: Set<SourceLanguage>? = nil, name: Name, markup: Markup, semantic: Semantic?, platformNames: Set<String>? = nil, isVirtual: Bool = false) {
         self.reference = reference
         self.kind = kind
         self.sourceLanguage = sourceLanguage
@@ -133,6 +136,7 @@ public struct DocumentationNode {
         self.symbol = nil
         self.platformNames = platformNames
         self.docChunks = [DocumentationChunk(source: .sourceCode(location: nil), markup: markup)]
+        self.isVirtual = isVirtual
         updateAnchorSections()
     }
 
@@ -171,6 +175,7 @@ public struct DocumentationNode {
         self.name = .symbol(declaration: .init([.plain(defaultSymbol.names.title)]))
         self.symbol = defaultSymbol
         self.unifiedSymbol = unifiedSymbol
+        self.isVirtual = moduleData.isVirtual
 
         self.markup = Document()
         self.docChunks = []
@@ -455,7 +460,6 @@ public struct DocumentationNode {
         case .`property`: return .instanceProperty
         case .`protocol`: return .protocol
         case .snippet: return .snippet
-        case .snippetGroup: return .snippetGroup
         case .`struct`: return .structure
         case .`subscript`: return .instanceSubscript
         case .`typeMethod`: return .typeMethod
@@ -564,6 +568,8 @@ public struct DocumentationNode {
             redirectsVariants: .init(swiftVariant: article?.redirects)
         )
 
+        self.isVirtual = symbol.isVirtual
+        
         updateAnchorSections()
     }
 
@@ -596,6 +602,7 @@ public struct DocumentationNode {
         self.availableSourceLanguages = [reference.sourceLanguage]
         self.docChunks = [DocumentationChunk(source: .documentationExtension, markup: articleMarkup)]
         self.markup = articleMarkup
+        self.isVirtual = false
 
         updateAnchorSections()
     }

Sources/SwiftDocC/Model/DocumentationNode.swift

@@ -25,8 +25,7 @@ extension DocumentationNode {
                  .volume,
                  .chapter,
                  .onPageLandmark,
-                 .snippet,
-                 .snippetGroup:
+                 .snippet:
                 return false
             default:
                 return true
@@ -156,9 +155,6 @@ extension DocumentationNode.Kind {
     public static let object = DocumentationNode.Kind(name: "Object", id: "org.swift.docc.kind.dictionary", isSymbol: true)
     /// A snippet.
     public static let snippet = DocumentationNode.Kind(name: "Snippet", id: "org.swift.docc.kind.snippet", isSymbol: true)
-    /// A group of snippets.
-    public static let snippetGroup = DocumentationNode.Kind(name: "Snippet Group", id: "org.swift.docc.kind.snippetGroup", isSymbol: true)
-
 
     /// The list of all known kinds of documentation nodes.
     /// - Note: The `unknown` value is not included.

Sources/SwiftDocC/Model/Kind.swift

@@ -210,36 +210,27 @@ struct RenderContentCompiler: MarkupVisitor {
     mutating func visitBlockDirective(_ blockDirective: BlockDirective) -> [RenderContent] {
         switch blockDirective.name {
         case Snippet.directiveName:
-            guard let snippetURL = blockDirective.arguments()[Snippet.Semantics.Path.argumentName],
+            let arguments = blockDirective.arguments()
+            guard let snippetURL = arguments[Snippet.Semantics.Path.argumentName],
                   let snippetReference = resolveSymbolReference(destination: snippetURL.value),
                   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 []
             }
-
-            let docCommentContent = snippetEntity.markup.children.flatMap { self.visit($0) }
-
-            let codeContent = snippetMixin.chunks.flatMap { chunk -> [RenderContent] in
-                guard !chunk.code.isEmpty else {
-                    return []
-                }
-
-                var elements = [RenderContent]()
-
-                if let chunkName = chunk.name {
-                    elements.append(RenderBlockContent.paragraph(inlineContent: [
-                        RenderInlineContent.strong(inlineContent: [
-                            RenderInlineContent.text(chunkName)
-                        ])
-                    ]))
-                }
-
-                elements.append(RenderBlockContent.codeListing(syntax: chunk.language, code: [chunk.code], metadata: nil))
-                return elements
+            
+            if let requestedSlice = arguments[Snippet.Semantics.Slice.argumentName]?.value,
+               let requestedLineRange = snippetMixin.slices[requestedSlice] {
+                // Render only the slice.
+                let lineRange = requestedLineRange.lowerBound..<min(requestedLineRange.upperBound, snippetMixin.lines.count)
+                let lines = snippetMixin.lines[lineRange]
+                return [RenderBlockContent.codeListing(syntax: snippetMixin.language, code: Array(lines), metadata: nil)]
+            } else {
+                // Render the whole snippet with its explanation content.
+                let docCommentContent = snippetEntity.markup.children.flatMap { self.visit($0) }
+                let code = RenderBlockContent.codeListing(syntax: snippetMixin.language, code: snippetMixin.lines, metadata: nil)
+                return docCommentContent + [code]
             }
-
-            return docCommentContent + codeContent
         default:
             return []
         }