Documentation - Typos & Consistency Fixes (#716) (#721)

Co-authored-by: Kyle <[email protected]>
Co-authored-by: Joey GM <[email protected]>

Author: 3 people

Sources/SwiftDocC/Benchmark/Metrics/TopicAnchorHash.swift

@@ -11,7 +11,7 @@
 import Foundation
 
 extension Benchmark {
-    /// A anchor sections hash metric produced off the given documentation context.
+    /// An anchor sections hash metric produced off the given documentation context.
     ///
     /// Use this metric to verify that your code changes
     /// did not affect the anchor sections in the compiled documentation.

Sources/SwiftDocC/Checker/Checkers/NonInclusiveLanguageChecker.swift

@@ -121,7 +121,7 @@ public struct NonInclusiveLanguageChecker: Checker {
 
     /// Checks for a term in text.
     ///
-    /// The regular expression created from the provided term is evaluated with the case insensitve flag.
+    /// The regular expression created from the provided term is evaluated with the case insensitive flag.
     ///
     /// - Parameters:
     ///   - term: The term to look for.

Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift

@@ -63,6 +63,9 @@ public class NavigatorIndex {
     public enum Error: Swift.Error, DescribedError {
 
         /// Missing bundle identifier.
+        case missingBundleIdentifier
+        
+        @available(*, deprecated, renamed: "missingBundleIdentifier")
         case missingBundleIndentifier
 
         /// A RenderNode has no title and won't be indexed.
@@ -72,8 +75,8 @@ public class NavigatorIndex {
         case navigatorIndexIsNil
 
         public var errorDescription: String {
-            switch self  {
-            case .missingBundleIndentifier:
+            switch self {
+            case .missingBundleIdentifier, .missingBundleIndentifier:
                 return "A navigator index requires a bundle identifier, which is missing."
             case .missingTitle:
                 return "The page has no valid title available."
@@ -175,7 +178,7 @@ public class NavigatorIndex {
         let bundleIdentifier = bundleIdentifier ?? information.get(type: String.self, forKey: NavigatorIndex.bundleKey) ?? NavigatorIndex.UnknownBundleIdentifier
 
         guard bundleIdentifier != NavigatorIndex.UnknownBundleIdentifier else {
-            throw Error.missingBundleIndentifier
+            throw Error.missingBundleIdentifier
         }
 
         // Use `.fnv1` by default if no path hasher is set for compatibility reasons.
@@ -237,7 +240,7 @@ public class NavigatorIndex {
         - url: The URL pointing to the path from which the index should be read.
         - bundleIdentifier: The name of the bundle the index is referring to.
         - readNavigatorTree: Indicates if the init needs to read the navigator tree from the disk, if false, then `readNavigatorTree` needs to be called later. Default: `true`.
-        - presentationIdentifier: Indicates if the index has an indentifier useful for presentation contexts.
+        - presentationIdentifier: Indicates if the index has an identifier useful for presentation contexts.
 
      - Throws: A `NavigatorIndex.Error` describing the nature of the problem.
 
@@ -282,7 +285,7 @@ public class NavigatorIndex {
         self.availabilityIndex = AvailabilityIndex()
 
         guard self.bundleIdentifier != NavigatorIndex.UnknownBundleIdentifier else {
-            throw Error.missingBundleIndentifier
+            throw Error.missingBundleIdentifier
         }
     }
 
@@ -577,10 +580,10 @@ extension NavigatorIndex {
         /// A temporary list of pending references that are waiting for their parent to be indexed.
         private var pendingUncuratedReferences = Set<Identifier>()
 
-        /// A map with all nodes that are curated mutliple times in the tree and need to be processed at the very end.
+        /// A map with all nodes that are curated multiple times in the tree and need to be processed at the very end.
         private var multiCurated = [Identifier: NavigatorTree.Node]()
 
-        /// A set with all nodes that are curated mutliple times, but still have to be visited.
+        /// A set with all nodes that are curated multiple times, but still have to be visited.
         private var multiCuratedUnvisited = Set<Identifier>()
 
         /// A set with all nodes that are curated.
@@ -747,7 +750,7 @@ extension NavigatorIndex {
                     }
                 }
 
-                // Sort the IDs so multiple entries with the same availiabilities
+                // Sort the IDs so multiple entries with the same availabilities
                 // will generate the same hash. In this way we can find them in the dictionary.
                 entryIDs.sort()
 

Sources/SwiftDocC/Indexing/Navigator/NavigatorTree.swift

@@ -31,7 +31,7 @@ public protocol Serializable: LMDBData, RawRepresentable where RawValue == Data
 
  The object needs to be conforming to `Serializable` so it can be transformed to raw data and reconstructed back using the same one.
 
- - Note: The `parentID` might be missing if the object is the root, but to avoid creating an exception on the the object structure, its id is set to 0.
+ - Note: The `parentID` might be missing if the object is the root, but to avoid creating an exception on the object structure, its id is set to 0.
  */
 public class NavigatorTree {
 
@@ -225,7 +225,7 @@ public class NavigatorTree {
         queue.append(root)
 
         var index: UInt32 = 0
-        while index < queue.count  {
+        while index < queue.count {
             let node = queue[Int(index)]
             node.id = index
             numericIdentifierToNode[index] = node

Sources/SwiftDocC/Indexing/RenderNode+Relationships.swift

@@ -22,7 +22,7 @@ extension RenderNode {
 
         switch kind {
         case .overview:
-            for case let section as VolumeRenderSection in sections  {
+            for case let section as VolumeRenderSection in sections {
                 let chapters = section.chapters
                 for chapter in chapters {
                     let name = chapter.name
@@ -67,7 +67,7 @@ extension RenderNode {
     */
     public func projectFiles() -> DownloadReference? {
         // sampleDownload is provided by pages which are of type "sample code".
-        // This section provides an action which includes a download referece.
+        // This section provides an action which includes a download reference.
         if let sampleDownload = sampleDownload, case let RenderInlineContent.reference(identifier, _, _, _) = sampleDownload.action,
            let reference = references[identifier.identifier] {
             return reference as? DownloadReference

Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift

@@ -29,7 +29,7 @@ struct DataAssetManager {
     var fuzzyKeyIndex = [String: String]()
 
     /**
-     Returns the data that is registered to an data asset with the specified trait collection.
+     Returns the data that is registered to a data asset with the specified trait collection.
 
      If no data is registered that exactly matches the trait collection, the data with the trait
      collection that best matches the requested trait collection is returned.

Sources/SwiftDocC/Infrastructure/Communication/Foundation/JSON.swift

@@ -77,7 +77,7 @@ extension JSON {
 
     subscript(key: Any) -> JSON? {
         get {
-            if let array = self.array, let index = key as? Int, index < array.count  {
+            if let array = self.array, let index = key as? Int, index < array.count {
                 return array[index]
             } else if let dic = self.dictionary, let key = key as? String, let obj = dic[key] {
                 return obj

Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift

@@ -318,7 +318,7 @@ extension CoverageDataEntry {
                         context: context))
             case .structure, .extendedStructure:
                 self = try .structure(
-                    memberStats:  KindSpecificData.extractChildStats(
+                    memberStats: KindSpecificData.extractChildStats(
                         documentationNode: documentationNode,
                         context: context))
             case .protocol, .extendedProtocol:
@@ -464,7 +464,7 @@ extension CoverageDataEntry.KindSpecificData {
 
         /// For cases that have an associated type `RatioStatistic`, the appropriate initializer for that case on `KindSpecificData`
         /// - Throws: If the instance does not represent a case with associated type `RatioStatistic`
-        /// - Returns: An closure that accepts an instance of `RatioStatistic` and returns an instance of `KindSpecificData`
+        /// - Returns: A closure that accepts an instance of `RatioStatistic` and returns an instance of `KindSpecificData`
         func associatedRatioStatisticInitializer() throws -> (RatioStatistic) -> CoverageDataEntry
             .KindSpecificData
         {
@@ -500,7 +500,7 @@ extension CoverageDataEntry.KindSpecificData {
 
         /// For cases that have an associated type `[InstanceMemberType: RatioStatistic]`, the appropriate initializer for that case on `KindSpecificData`
         /// - Throws: If the instance does not represent a case with associated type `RatioStatistic`
-        /// - Returns: An closure that accepts an instance of `[InstanceMemberType: RatioStatistic]` and returns an instance of `KindSpecificData`
+        /// - Returns: A closure that accepts an instance of `[InstanceMemberType: RatioStatistic]` and returns an instance of `KindSpecificData`
         func associatedMemberStatisticsInitializer() throws -> ([InstanceMemberType: RatioStatistic]) -> CoverageDataEntry
             .KindSpecificData
         {

Sources/SwiftDocC/Infrastructure/Diagnostics/Diagnostic.swift

@@ -42,7 +42,7 @@ public struct Diagnostic {
         return summary
     }
 
-    /// Additional details that explain the the problem or issue to the end-user in plain language.
+    /// Additional details that explain the problem or issue to the end-user in plain language.
     public var explanation: String?
 
     @available(*, deprecated, renamed: "explanation")

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -258,7 +258,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
     /// The mapping of external symbol identifiers to known disambiguated symbol path components.
     ///
-    /// In situations where the the local documentation context doesn't contain all of the current module's
+    /// In situations where the local documentation context doesn't contain all of the current module's
     /// symbols, for example when using a ``ConvertService`` with a partial symbol graph,
     /// the documentation context is otherwise unable to accurately detect a collision for a given symbol and correctly
     /// disambiguate its path components. This value can be used to inject already disambiguated symbol
@@ -435,7 +435,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// - Parameter moduleReference: The module reference to find the module name for.
     /// - Returns: The plain string name for the referenced module.
     func moduleName(forModuleReference moduleReference: ResolvedTopicReference) -> (displayName: String, symbolName: String) {
-        if let name = moduleNameCache[moduleReference]  {
+        if let name = moduleNameCache[moduleReference] {
             return name
         }
         // If no name is found it's considered a programmer error; either that the names haven't been resolved yet
@@ -2543,7 +2543,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
     // MARK: - Relationship queries
 
-    /// Fetch the child nodes of a documentation node with the given `reference``,  optionally filtering to only children of the given `kind`.
+    /// Fetch the child nodes of a documentation node with the given `reference`, optionally filtering to only children of the given `kind`.
     ///
     /// - Parameters:
     ///   - reference: The reference of the node to fetch children for.
@@ -2669,7 +2669,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// - Parameters:
     ///   - name: The name of the asset.
     ///   - parent: The topic where the asset is referenced.
-    /// - Returns: The data that's associated with a image asset if it was found, otherwise `nil`.
+    /// - Returns: The data that's associated with an image asset if it was found, otherwise `nil`.
     public func resolveAsset(named name: String, in parent: ResolvedTopicReference, withType type: AssetType? = nil) -> DataAsset? {
         let bundleIdentifier = parent.bundleIdentifier
         return resolveAsset(named: name, bundleIdentifier: bundleIdentifier, withType: type)

Sources/SwiftDocC/Infrastructure/External Data/ExternalSymbolResolver.swift

@@ -17,7 +17,7 @@ import Foundation
 ///  * Resolve authored symbol references and return the precise identifier for the resolved symbol.
 ///  * Return an external URL for the references that it was able to resolve.
 ///
-/// If a symbol in a symbol graph file references a type that's not in the local bundle — for a example, the symbol conforms to a protocol that's not defined in the local bundle, the
+/// If a symbol in a symbol graph file references a type that's not in the local bundle — for example, the symbol conforms to a protocol that's not defined in the local bundle, the
 /// symbol inherits from a class that's not defined in the local bundle, or the symbol has arguments or return values that are types which are not defined in the local bundle —
 /// then this external resolver can resolve those symbol references. This allows references in symbol declarations to be turned into links for external references, just like in-bundle
 /// symbol references can be.

Sources/SwiftDocC/Infrastructure/External Data/FallbackReferenceResolver.swift

@@ -10,7 +10,7 @@
 
 import Foundation
 
-/// An reference resolver that can be used to resolve references that couldn't be resolved locally.
+/// A reference resolver that can be used to resolve references that couldn't be resolved locally.
 ///
 /// Fallback reference resolvers are used by a ``DocumentationContext`` to resolve externally resolve references that
 /// couldn't be resolved internally.

Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy.swift

@@ -51,7 +51,7 @@ struct PathHierarchy {
 
     // MARK: Creating a path hierarchy
 
-    /// Initializes a path hierarchy with the all the symbols from all modules that a the given symbol graph loader provides.
+    /// Initializes a path hierarchy with all the symbols from all modules that the given symbol graph loader provides.
     ///
     /// - Parameters:
     ///   - loader: The symbol graph loader that provides all symbols.

Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchyBasedLinkResolver.swift

@@ -161,7 +161,7 @@ final class PathHierarchyBasedLinkResolver {
         addAnchors(anchorSections, to: articleID)
     }
 
-    /// Adds a article and its headings to the path hierarchy.
+    /// Adds an article and its headings to the path hierarchy.
     func addArticle(filename: String, reference: ResolvedTopicReference, anchorSections: [AnchorSection]) {
         let articleID = pathHierarchy.addArticle(name: filename)
         resolvedReferenceMap[articleID] = reference

Sources/SwiftDocC/Infrastructure/Symbol Graph/ExtendedTypeFormatExtension.swift

@@ -17,7 +17,7 @@ extension SymbolGraph.Relationship.Kind {
     /// respective extended module symbol.
     static let declaredIn = Self(rawValue: "declaredIn")
 
-    /// This relationship markes a parent-child hierarchy between a nested
+    /// This relationship marks a parent-child hierarchy between a nested
     /// extended type symbol and its parent extended type symbol. It mirrors the
     /// `memberOf` relationship between the two respective original type symbols.
     static let inContextOf = Self(rawValue: "inContextOf")

Sources/SwiftDocC/Infrastructure/Symbol Graph/ExtendedTypeFormatTransformation.swift

@@ -202,7 +202,7 @@ extension ExtendedTypeFormatTransformation {
             }
 
             for source in source(target) {
-                if case (.some(_), .some(_)) =  (target.docComment, source.docComment) {
+                if case (.some(_), .some(_)) = (target.docComment, source.docComment) {
                     target.docComment = resolveConflict(target, source)
                 } else {
                     target.docComment = target.docComment ?? source.docComment
@@ -314,7 +314,7 @@ extension ExtendedTypeFormatTransformation {
 
         extensionBlockToExtendedTypeMapping.reserveCapacity(extensionBlockSymbols.count)
 
-        let createExtendedTypeSymbolAndAnchestors = { (extensionBlockSymbol: SymbolGraph.Symbol, id: String) -> SymbolGraph.Symbol in
+        let createExtendedTypeSymbolAndAncestors = { (extensionBlockSymbol: SymbolGraph.Symbol, id: String) -> SymbolGraph.Symbol in
             var newMixins = [String: Mixin]()
 
             if var swiftExtension = extensionBlockSymbol[mixin: SymbolGraph.Symbol.Swift.Extension.self] {
@@ -365,7 +365,7 @@ extension ExtendedTypeFormatTransformation {
 
             let symbol: SymbolGraph.Symbol = extendedTypeSymbols[extendedSymbolId]?.replacing(\.accessLevel) { oldSymbol in
                 max(oldSymbol.accessLevel, extensionBlockSymbol.accessLevel)
-            } ?? createExtendedTypeSymbolAndAnchestors(extensionBlockSymbol, extendedSymbolId)
+            } ?? createExtendedTypeSymbolAndAncestors(extensionBlockSymbol, extendedSymbolId)
 
             pathComponentToExtendedTypeMapping[symbol.pathComponents[...]] = symbol.identifier.precise
 
@@ -385,7 +385,7 @@ extension ExtendedTypeFormatTransformation {
     /// - ``SymbolKit/SymbolGraph/Symbol/KindIdentifier/unknownExtendedType``
     ///
     /// If a nested type is extended, but its parent (or another ancestor) is not, this ancestor is not part of the
-    /// extension block symbol format. In that case, a extended type symbol of unknown kind is synthesized by
+    /// extension block symbol format. In that case, an extended type symbol of unknown kind is synthesized by
     /// this function. However, if the ancestor symbol is extended, the `extendedTypeSymbols` should
     /// already contain the respective symbol. In that case, the ``SymbolKit/SymbolGraph/Relationship/inContextOf``
     /// is attached to the existing symbol.

Sources/SwiftDocC/Infrastructure/Symbol Graph/GeneratedDocumentationTopics.swift

@@ -220,7 +220,7 @@ enum GeneratedDocumentationTopics {
         }
     }
 
-    /// Creates a API collection in the given documentation context for all inherited symbols according to the symbol graph.
+    /// Creates an API collection in the given documentation context for all inherited symbols according to the symbol graph.
     ///
     /// Inspects the given symbol relationships and extracts all inherited symbols into a separate level in the documentation hierarchy -
     /// an API collection called "Inherited APIs" where all inherited symbols are listed unless they are manually curated in

Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolGraphConcurrentDecoder.swift

@@ -104,7 +104,7 @@ enum SymbolGraphConcurrentDecoder {
         // Wait until all concurrent tasks have completed.
         group.wait()
 
-        // If an error happend during decoding re-throw.
+        // If an error happened during decoding re-throw.
         if let lastError = decodeError.sync({ $0 }) {
             throw lastError
         }

Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolGraphLoader.swift

@@ -258,7 +258,7 @@ struct SymbolGraphLoader {
     /// Returns the module name, if any, in the file name of a given symbol-graph URL.
     ///
     /// Returns "Combine", if it's a main symbol-graph file, such as "Combine.symbols.json".
-    ///  Returns "Swift", if it's an extension file such as, "[email protected]".
+    /// Returns "Swift", if it's an extension file such as, "[email protected]".
     /// - parameter url: A URL to a symbol graph file.
     /// - returns: A module name, or `nil` if the file name cannot be parsed.
     static func moduleNameFor(_ url: URL) -> String? {

Sources/SwiftDocC/Infrastructure/Workspace/DocumentationWorkspace.swift

@@ -20,7 +20,7 @@ import Foundation
 /// ``DocumentationContextDataProvider/bundles`` and allows the context to access the contents of the various bundles without knowing any specifics
 /// of its source (files on disk, a database, or a web services).
 ///
-/// The second lets the the workspace notify the context when bundles are added or removed so that the context stays up to date, even after the context is created.
+/// The second lets the workspace notify the context when bundles are added or removed so that the context stays up to date, even after the context is created.
 ///
 /// ```
 ///                                                                                       ┌─────┐

Sources/SwiftDocC/Infrastructure/Workspace/DocumentationWorkspaceDataProvider.swift

@@ -15,7 +15,7 @@ public protocol DocumentationWorkspaceDataProvider {
     /// A string that uniquely identifies this data provider.
     ///
     /// Unless your implementation needs a stable identifier to associate with an external system, it's reasonable to
-    /// use `UUID().uuidString`  for the provider's identifier.
+    /// use `UUID().uuidString` for the provider's identifier.
     var identifier: String { get }
 
     /// Returns the data backing one of the files that this data provider provides.