Merge branch 'main' into readable-symbol-link-disambiguation

CONTRIBUTING.md

@@ -49,6 +49,9 @@ more details.
 
 ## Building Swift-DocC
 
+`docc` is the command line interface (CLI) for Swift-DocC and provides
+support for generating and previewing documentation.
+
 ### Prerequisites
 
 Swift-DocC is a Swift package. If you're new to Swift package manager,
@@ -99,7 +102,7 @@ You can run your newly built version of `docc` with:
   ```
 
 Or, in Xcode, run the `docc`
-[scheme](https://developer.apple.com/library/archive/documentation/ToolsLanguages/Conceptual/Xcode_Overview/ManagingSchemes.html).
+[scheme](https://developer.apple.com/documentation/xcode/customizing-the-build-schemes-for-a-project).
 
 ### Miscellaneous
 
@@ -261,7 +264,7 @@ export DOCC_HTML_DIR="/path/to/swift-docc-render-artifact/dist"
 
 The `docc preview` command performs a conversion of your documentation and
 starts a local web server to allow for easy previewing of the built documentation.
-It monitors the provided Documentation Catalog for changes and updates the preview
+It monitors the provided documentation catalog for changes and updates the preview
 as you're working.
 
 ```sh
@@ -436,4 +439,65 @@ page.
 Once you've found an issue to work on,
 follow the above instructions for [Building Swift-DocC](#building-swift-docc).
 
-<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+## Technical Overview and Related Projects
+
+Swift-DocC builds documentation by combining _Symbol Graph_ files that contains API information 
+with a `.docc` documentation catalog that contains articles and tutorials
+to create a final archive with the compiled documentation.
+
+More concretely, Swift-DocC understands the following kinds of inputs:
+
+ 1. _Symbol Graph_ files with the `.symbols.json` extension.
+   _Symbol Graph_ files are a machine-readable representation of a module's APIs, 
+   including their documentation comments and relationship with one another.
+
+ 2. A documentation catalog directory with the `.docc` extension. 
+   Documentation catalogs can include additional documentation content like the following:
+
+   - Documentation markup files with the `.md` extension. Documentation markup files can
+    be used to write articles and to extend documentation for symbols.
+
+   - Tutorial files with the `.tutorial` extension. Tutorial files are used to author
+    step-by-step instructions on how to use a framework.
+
+   - Additional documentation assets with known extensions like `.png`, `.jpg`, `.mov`,
+    and `.zip`.
+
+   - An `Info.plist` file containing metadata such as the name of the documented module. 
+    This file is optional and the information it contains can be passed via the command line.
+
+Swift-DocC outputs a machine-readable archive of the compiled documentation.
+This archive contains _render JSON_ files, which fully describe the contents
+of a documentation page and can be processed by a renderer such as
+[Swift-DocC-Render](https://github.com/apple/swift-docc-render).
+
+For more in-depth technical information about Swift-DocC, please refer to the
+project's technical documentation:
+
+- [`SwiftDocC` framework documentation](https://apple.github.io/swift-docc/documentation/swiftdocc/)
+- [`SwiftDocCUtilities` framework documentation](https://apple.github.io/swift-docc/documentation/swiftdoccutilities/)
+
+### Related Projects
+
+ - As of Swift 5.5, the [Swift Compiler](https://github.com/apple/swift) is able to 
+  emit _Symbol Graph_ files as part of the compilation process.
+   
+ - [SymbolKit](https://github.com/apple/swift-docc-symbolkit) is a Swift package containing
+  the specification and reference model for the _Symbol Graph_ File Format.
+  
+ - [Swift Markdown](https://github.com/apple/swift-markdown) is a 
+  Swift package for parsing, building, editing, and analyzing 
+  Markdown documents. It includes support for the Block Directive elements
+  that Swift-DocC's tutorial files rely on.
+
+ - [Swift-DocC-Render](https://github.com/apple/swift-docc-render) 
+  is a web application that understands and renders
+  Swift-DocC's _render JSON_ format.
+   
+ - [Xcode](https://developer.apple.com/xcode/) consists of a suite of
+  tools that developers use to build apps for Apple platforms.
+  Beginning with Xcode 13, Swift-DocC is integrated into Xcode
+  with support for building and viewing documentation for your framework and
+  its dependencies.
+
+<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Package.resolved

@@ -60,7 +60,7 @@
       "location" : "https://github.com/apple/swift-docc-symbolkit",
       "state" : {
         "branch" : "main",
-        "revision" : "53e5cb9b18222f66cb8d6fb684d7383e705e0936"
+        "revision" : "31ee554ce4bed5fa05eea36bc30296f7d4149097"
       }
     },
     {
@@ -78,7 +78,7 @@
       "location" : "https://github.com/apple/swift-markdown.git",
       "state" : {
         "branch" : "main",
-        "revision" : "36b71b380ca9cb7497fc24416f8b77721eaf7330"
+        "revision" : "e5ab90941a8415304b4a4e403253bd59fef00b5a"
       }
     },
     {

README.md

@@ -1,180 +1,67 @@
 # Swift-DocC
 
 Swift-DocC is a documentation compiler for Swift frameworks and packages aimed 
-at making it easy to write and publish great developer documentation.
+at making it easy to write and publish great developer documentation
 
 For an example of Swift-DocC in action, check out 
 [developer.apple.com](https://developer.apple.com/documentation).
 Much of Apple's developer documentation,
 from [Reference documentation](https://developer.apple.com/documentation/GroupActivities)
 to [Tutorials](https://developer.apple.com/tutorials/swiftui),
+and [long-form content](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/)
 is built using Swift-DocC.
 
+To learn more about the essentials of this tool 
+refer to the
+[user documentation](https://www.swift.org/documentation/docc).
+
 Swift-DocC is being actively developed. For more information about the
 Swift-DocC project, see the introductory blog post
 [here](https://swift.org/blog/swift-docc/).
 
-The latest documentation for the Swift-DocC project is available
-on [Swift.org](https://swift.org/documentation/docc).
-
-The [Swift Forums](https://forums.swift.org/c/development/swift-docc) are
-the best place to get help with Swift-DocC and discuss future plans.
-
-## Writing and Publishing Documentation with Swift-DocC
-
-If you're looking to write and publish documentation with Swift-DocC, 
-the best way to get started is with Swift-DocC's
-[user documentation](https://www.swift.org/documentation/docc).
-
-## Technical Overview and Related Projects
-
-Swift-DocC builds documentation by combining _Symbol Graph_ files containing API information 
-with a `.docc` Documentation Catalog containing articles and tutorials
-to create a final archive containing the compiled documentation.
-
-More concretely, Swift-DocC understands the following kinds of inputs:
-
-  1. _Symbol Graph_ files with the `.symbols.json` extension.
-     _Symbol Graph_ files are a machine-readable representation of a module's APIs, 
-     including their documentation comments and relationship with one another.
-
-  2. A Documentation Catalog with the `.docc` extension. 
-     Documentation Catalogs can include additional documentation content like the following:
-
-     - Documentation markup files with the `.md` extension. Documentation markup files can
-       be used to extend documentation for symbols and to write free-form articles.
-
-     - Tutorial files with the `.tutorial` extension. Tutorial files are used to author
-       step-by-step instructions on how to use a framework.
-
-     - Additional documentation assets with known extensions like `.png`, `.jpg`, `.mov`,
-       and `.zip`.
-
-     - An `Info.plist` file containing metadata such as the name of the documented module. 
-       This file is optional and the information it contains can be passed via the command line.
-
-Swift-DocC outputs a machine-readable archive of the compiled documentation.
-This archive contains _render JSON_ files, which fully describe the contents
-of a documentation page and can be processed by a renderer such as
-[Swift-DocC-Render](https://github.com/apple/swift-docc-render).
-
-For more in-depth technical information about Swift-DocC, please refer to the
-project's technical documentation:
-
-- [`SwiftDocC` framework documentation](https://apple.github.io/swift-docc/documentation/swiftdocc/)
-- [`SwiftDocCUtilities` framework documentation](https://apple.github.io/swift-docc/documentation/swiftdoccutilities/)
-
-### Related Projects
-
-  - As of Swift 5.5, the [Swift Compiler](https://github.com/apple/swift) is able to 
-    emit _Symbol Graph_ files as part of the compilation process.
-
-  - [SymbolKit](https://github.com/apple/swift-docc-symbolkit) is a Swift package containing
-    the specification and reference model for the _Symbol Graph_ File Format.
-
-  - [Swift Markdown](https://github.com/apple/swift-markdown) is a 
-    Swift package for parsing, building, editing, and analyzing 
-    Markdown documents. It includes support for the Block Directive elements
-    that Swift-DocC's tutorial files rely on.
-
-  - [Swift-DocC-Render](https://github.com/apple/swift-docc-render) 
-    is a web application that understands and renders
-    Swift-DocC's _render JSON_ format.
-
-  - [Xcode](https://developer.apple.com/xcode/) consists of a suite of
-    tools that developers use to build apps for Apple platforms.
-    Beginning with Xcode 13, Swift-DocC is integrated into Xcode
-    with support for building and viewing documentation for your framework and
-    its dependencies.
-
-## Getting started with developing `docc`
+## Getting Started with DocC
 
 `docc` is the command line interface (CLI) for Swift-DocC and provides
-support for converting and previewing DocC documentation.
-
-### Prerequisites
-
-DocC is a Swift package. If you're new to Swift package manager,
-the [documentation here](https://swift.org/getting-started/#using-the-package-manager)
-provides an explanation of how to get started and the software you'll need
-installed.
-
-DocC requires Swift 5.5 which is included in Xcode 13.
-
-### Build
+support for generating and previewing documentation.
 
-1. Checkout this repository using:
+There are multiple ways you can make use of DocC depending on your use case:
 
-    ```bash
-    git clone https://github.com/apple/swift-docc.git
-    ```
+**1. For documenting packages via SwiftPM:**
 
-2. Navigate to the root of the repository with:
-
-    ```bash
-    cd swift-docc
-    ```
-
-3. Finally, build DocC by running:
-
-    ```bash
-    swift build
-    ```
-
-### Run
-
-To run `docc`, run the following command:
-
-  ```bash
-  swift run docc
-  ```
-
-### Installing into Xcode
-
-You can test a locally built version of Swift-DocC in Xcode 13 or later by setting
-the `DOCC_EXEC` build setting to the path of your local `docc`:
+If you want to generate documentation for your Swift package we recommend using the Swift-DocC Plugin. Please
+refer to the Plugin's [documentation](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/) to get started with 
+[building](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-a-specific-target), [previewing](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/previewing-documentation),
+and publishing your documentation to your [website](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-hosting-online) or [GitHub Pages](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/publishing-to-github-pages).
 
-  1. Select the project in the Project Navigator.
-
-  2. In the Build Settings tab, click '+' and then 'Add User-Defined Setting'. 
-
-  3. Create a build setting `DOCC_EXEC` with the value set to `/path/to/docc`. 
+**2. For standalone documentation:**
 
-The next time you invoke a documentation build with the "Build Documentation"
-button in Xcode's Product menu, your custom `docc` will be used for the build.
-You can confirm that your custom `docc` is being used by opening the latest build
-log in Xcode's report navigator and expanding the "Compile documentation" step.
+If you have Xcode installed, it's recommended to generate documentation using the `xcrun` command.
+You can get DocC working by invoking `xcrun docc` in your terminal.
 
-### Invoking `docc` from Swift Package Manager
+Swift-DocC is also included in the Swift toolchain for both macOS and Linux.
 
-You can also test a locally built version of Swift-DocC using the Swift Package
-Manager from the command line. The Swift-DocC SwiftPM plugin will try to read
-`DOCC_EXEC` environment variable value, and use the path you provded if it's set.
+To see instructions on how to use DocC from the CLI run
+```
+docc --help
+```
 
-  1. In your project's `Package.swift`, add a dependency on the [`Swift-DocC Plugin`](https://github.com/apple/swift-docc-plugin).
-  2. Set the `DOCC_EXEC` environment variable and run the documentation generation
-     command:
+**3. For documenting apps, frameworks, and packages using Xcode:**
 
-        ```bash
-        DOCC_EXEC=/path/to/docc swift package generate-documentation
-        ```
+If you want to generate an API reference for your project you can use DocC via Xcode.
+Please refer to the Xcode [documentation](https://developer.apple.com/documentation/xcode/writing-documentation)
+to learn the essentials of how to get started.
 
-## Using `docc` to build and preview documentation
+## Writing and Publishing Documentation with Swift-DocC
 
-The preferred way of building documentation for your Swift package is by using
-the Swift-DocC Plugin, or if you're using Xcode, using the "Build Documentation" command. 
+If you want to learn how to write and format your documentation please refer to
+[Formatting Your Documentation Content](https://www.swift.org/documentation/docc/formatting-your-documentation-content).
+For publishing go to [Distributing Documentation to Other Developers](https://www.swift.org/documentation/docc/distributing-documentation-to-other-developers).
 
-Refer to instructions in the plugin's 
-[documentation](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/)
-to get started with [building](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-a-specific-target), [previewing](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/previewing-documentation),
-and publishing your documentation to your [website](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-hosting-online) or [GitHub Pages](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/publishing-to-github-pages).
+To learn more about how Swift-DocC works internally please see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Alternatively, you can manually generate symbol graph files and invoke `docc` directly. 
-Refer to instructions in [CONTRIBUTING.md](/CONTRIBUTING.md#assembling-symbol-graphs-and-building-with-docc-directly).
-
 ## Versioning
 
-Swift-DocC's CLI tool (`docc`) will be integrated into the Swift toolchain 
+Swift-DocC's CLI tool (`docc`) is integrated into the Swift toolchain 
 and follows the Swift compiler's versioning scheme.
 
 The `SwiftDocC` library is versioned separately from `docc`. `SwiftDocC` is under
@@ -200,7 +87,7 @@ and provide as many details as possible.
 
 If you can confirm that the bug occurs when using the latest commit of Swift-DocC
 from the `main` branch (see [Building Swift-DocC](/CONTRIBUTING.md#building-swift-docc)),
-that will help us track down the bug faster.
+it will help us track down the bug faster..
 
 ### Submitting a Feature Request
 
@@ -217,6 +104,11 @@ before being enabled by default.
 
 ## Contributing to Swift-DocC
 
-Please see the [contributing guide](/CONTRIBUTING.md) for more information.
+The [Swift Forums](https://forums.swift.org/c/development/swift-docc) are
+the best place to get help with Swift-DocC and discuss future plans.
+
+As an open-source project, we value any contribution made to this tool.
+Please see the [contributing guide](/CONTRIBUTING.md) for more information on how to 
+contribute and build DocC from source.
 
-<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

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/DocumentationService/Models/Services/Convert/ConvertRequest.swift

@@ -132,9 +132,9 @@ public struct ConvertRequest: Codable {
 
     /// The symbol identifiers that have an expanded documentation page available if they meet the associated access level requirement.
     ///
-    /// DocC sets the ``RenderMetadata/hasExpandedDocumentationForSymbols`` property to `true`
-    /// for these symbols if they meet the provided  requirements, so that renderers can display a "View More" link
-    /// that navigates the user to the full version of the documentation page.
+    /// For each of these symbols DocC sets the ``RenderMetadata/hasNoExpandedDocumentation`` property to `true`
+    /// if the symbol fails to meet its provided requirements. This information in the page's ``RenderMetadata`` can be used to display
+    /// a "View More" link that navigates the user to the full version of the documentation page.
     public var symbolIdentifiersWithExpandedDocumentation: [String: ExpandedDocumentationRequirements]?
 
     /// The default code listing language for the documentation bundle to convert.