Merge branch 'swift-5.2'

Author: mattt

.github/workflows/ci.yml

@@ -3,27 +3,23 @@ name: CI
 on: [push]
 
 jobs:
-  macos:
-    runs-on: macOS-latest
+  # macos:
+  #   runs-on: macOS-latest
 
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v1
-      - name: Build and Run
-        run: swift run swift-doc Sources
+  #   steps:
+  #     - name: Checkout
+  #       uses: actions/checkout@v1
+  #     - name: Build and Test
+  #       run: swift test
 
   linux:
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        swift: ["5.1"]
-
     container:
-      image: swift:${{ matrix.swift }}
+      image: swiftlang/swift:nightly-5.2-xenial
 
     steps:
       - name: Checkout
         uses: actions/checkout@v1
       - name: Build and Run
-        run: swift run swift-doc Sources
+        run: swift run swift-doc Sources/SwiftDoc

Package.resolved

@@ -9,34 +9,31 @@ let package = Package(
         .library(name: "SwiftDoc", targets: ["SwiftDoc"])
     ],
     dependencies: [
+        .package(url: "https://github.com/apple/swift-syntax.git", .revision("0.50200.0")),
+        .package(url: "https://github.com/SwiftDocOrg/SwiftSemantics.git", .branch("swift-5.2")),
         .package(url: "https://github.com/SwiftDocOrg/CommonMark.git", .branch("master")),
         .package(url: "https://github.com/SwiftDocOrg/SwiftMarkup.git", .upToNextMinor(from: "0.0.4")),
-        .package(url: "https://github.com/SwiftDocOrg/SwiftSemantics.git", .branch("master")),
-        .package(url: "https://github.com/apple/swift-syntax.git", .exact("0.50100.0")),
-        .package(url: "https://github.com/kylef/Commander.git", .upToNextMinor(from: "0.9.1")),
+        .package(url: "https://github.com/SwiftDocOrg/GraphViz.git", .upToNextMinor(from: "0.0.1")),
+        .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(from: "0.0.2")),
     ],
     targets: [
         // Targets are the basic building blocks of a package. A target can define a module or a test suite.
         // Targets can depend on other targets in this package, and on products in packages which this package depends on.
         .target(
             name: "swift-doc",
-            dependencies: ["SwiftDoc", "SwiftSemantics", "SwiftMarkup", "CommonMarkBuilder", "Commander"]
+            dependencies: ["ArgumentParser", "SwiftDoc", "SwiftSemantics", "SwiftMarkup", "CommonMarkBuilder", "DCOV", "GraphViz"]
         ),
         .target(
-            name: "swift-dcov",
-            dependencies: ["SwiftSyntax", "SwiftSemantics", "SwiftMarkup", "SwiftDoc", "Commander"]
-        ),
-        .target(
-            name: "swift-api-diagram",
-            dependencies: ["SwiftDoc", "SwiftSemantics", "Commander"]
-        ),
-        .target(
-            name: "swift-api-inventory",
-            dependencies: ["SwiftDoc", "SwiftSemantics", "Commander"]
+            name: "DCOV",
+            dependencies: []
         ),
         .target(
             name: "SwiftDoc",
             dependencies: ["SwiftSyntax", "SwiftSemantics", "SwiftMarkup"]
         ),
+        .testTarget(
+            name: "SwiftDocTests",
+            dependencies: ["SwiftDoc", "SwiftSyntax", "SwiftSemantics", "SwiftMarkup"]
+        ),
     ]
 )

Package.swift

@@ -63,89 +63,23 @@ By default,
 output files are written to `.build/documentation`,
 but you can change that with the `--output` option flag.
 
-## GitHub Action
-
-This repository also hosts a [GitHub Action][github actions]
-that you can incorporate into your project's workflow.
-
-The CommonMark files generated by `swift-doc`
-are formatted for publication to your project's [GitHub Wiki][github wiki],
-which you can do with
-[github-wiki-publish-action][github-wiki-publish-action].
-Alternatively,
-you could publish `swift-doc`-generated documentation to GitHub Pages,
-or bundle them into a release artifact.
-
-### Inputs
-
-- `inputs`:
-  One or more paths to Swift files in your workspace.
-  (Default: `"./Sources"`)
-- `output`:
-  The path for generated output.
-  (Default: `"./.build/documentation"`)
-
-### Example Workflow
-
-```yml
-# .github/workflows/documentation.yml
-name: Documentation
-
-on: [push]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v1
-      - name: Generate Documentation
-        uses: SwiftDocOrg/swift-doc@master
-        with:
-          inputs: "Source"
-          output: "Documentation"
-      - name: Upload Documentation to Wiki
-        uses: SwiftDocOrg/github-wiki-publish-action@master
-        with:
-          path: "Documentation"
-        env:
-          GITHUB_PERSONAL_ACCESS_TOKEN: ${{ secrets.GITHUB_PERSONAL_ACCESS_TOKEN }}
-```
+#### swift-doc coverage
 
-## Experimental Command-Line Tools
-
-In addition to `swift-doc`,
-this project currently ships with several, experimental tools
-that offer complementary functionality.
-It's unclear how everything will ultimately fit together,
-but for now,
-they're incubating in a shared monorepo
-(the intent is for each of them to eventually become
-an option, subcommand, or plugin of `swift-doc`).
-
-> **Note**:
-> We recommend building and running these tools via `swift run`.
-> If you prefer to have compiled binaries,
-> you can generate them with the same commands
-> used for the `swift-doc` target in `Makefile`.
-
-* * *
-
-### swift-dcov
-
-`swift-dcov` generates documentation coverage statistics for Swift files.
+The `coverage` subcommand 
+generates documentation coverage statistics for Swift files.
 
 ```terminal
 $ git clone https://github.com/SwiftDocOrg/SwiftSemantics.git
 
-$ swift run swift-dcov SwiftSemantics/Sources/ | jq ".data.totals"
+$ swift run swift-doc coverage SwiftSemantics/Sources/ --output "dcov.json" 
+$ cat dcov.json | jq ".data.totals"
 {
   "count": 207,
   "documented": 199,
   "percent": 96.1352657004831
 }
 
-$ swift run swift-dcov SwiftSemantics/Sources/ | jq ".data.symbols[] | select(.documented == false)"
+$ cat dcov.json | jq ".data.symbols[] | select(.documented == false)"
 {
   "file": "SwiftSemantics/Supporting Types/GenericRequirement.swift",
   "line": 67,
@@ -167,86 +101,14 @@ If you know of an existing standard
 that you think might be better suited for this purpose,
 please reach out by [opening an Issue][open an issue]!
 
-### swift-api-inventory
-
-`swift-api-inventory` lists the public API symbols of Swift files.
-
-```terminal
-$ git clone https://github.com/SwiftDocOrg/SwiftSemantics.git
-
-$ swift run swift-api-inventory SwiftSemantics/Sources | less
-struct AssociatedType: Declaration, Hashable, Codable, ExpressibleBySyntax
-var AssociatedType.attributes { get }
-var AssociatedType.context { get }
-var AssociatedType.keyword { get }
-var AssociatedType.modifiers { get }
-var AssociatedType.name { get }
-...
-
-$ swift run swift-api-inventory SwiftSemantics/Sources | wc
-     207    1023    8993
-```
-
-Because each symbol is printed on its own line,
-you can feed the output of `swift-api-inventory` to conventional diffing tools
-to determine API changes between different releases of a project.
+#### swift-doc diagram
 
-For example,
-here's an API diff between the first beta and latest release candidate of
-[Alamofire 5](https://forums.swift.org/t/alamofire-5-one-year-in-the-making-now-in-beta/18865):
-
-```terminal
-$ git clone https://github.com/Alamofire/Alamofire.git
-$ (cd Alamofire; git co 5.0.0-beta.1; swift run swift-api-inventory Source > ../Alamofire-5.0.0-beta.1.txt)
-$ (cd Alamofire; git co 5.0.0-rc.3; swift run swift-api-inventory Source > ../Alamofire-5.0.0-rc.3.txt)
-$ diff -u Alamofire-5.0.0-beta.1.txt Alamofire-5.0.0-rc.3.txt | diffstat
- Alamofire-5.0.0-rc.3.txt |  346 ++++++++++++++++++++++++++++++++—————
- 1 file changed, 238 insertions(+), 108 deletions(-)
-```
-
-<details>
-
-<summary>Example diff between Alamofire 5 RC3 and RC1</summary>
-
-```terminal
-$ diff -u Alamofire-5.0.0-rc.1.txt Alamofire-5.0.0-rc.3.txt
-```
-
-```diff
-— Alamofire-5.0.0-rc.1.txt
-+++ Alamofire-5.0.0-rc.3.txt
-@@ -77,6 +77,7 @@
- case AFError.ServerTrustFailureReason.revocationCheckFailed(output: Output, options: RevocationTrustEvaluator.Options)
- case AFError.ServerTrustFailureReason.revocationPolicyCreationFailed
- case AFError.ServerTrustFailureReason.settingAnchorCertificatesFailed(status: OSStatus, certificates: [SecCertificate])
-+case AFError.ServerTrustFailureReason.trustEvaluationFailed(error: Error?)
- enum AFError.URLRequestValidationFailureReason
- case AFError.URLRequestValidationFailureReason.bodyDataInGETRequest(_: Data)
- case AFError.createURLRequestFailed(error: Error)
-@@ -613,13 +614,14 @@
- case URLEncodedFormEncoder.SpaceEncoding.percentEscaped
- case URLEncodedFormEncoder.SpaceEncoding.plusReplaced
- var URLEncodedFormEncoder.allowedCharacters { get set }
-+var URLEncodedFormEncoder.alphabetizeKeyValuePairs { get }
- var URLEncodedFormEncoder.arrayEncoding { get }
- var URLEncodedFormEncoder.boolEncoding { get }
- var URLEncodedFormEncoder.dataEncoding { get }
- var URLEncodedFormEncoder.dateEncoding { get }
- func URLEncodedFormEncoder.encode(_: Encodable) throws -> String
- func URLEncodedFormEncoder.encode(_: Encodable) throws -> Data
--init URLEncodedFormEncoder(arrayEncoding: ArrayEncoding, boolEncoding: BoolEncoding, dataEncoding: DataEncoding, dateEncoding: DateEncoding, keyEncoding: KeyEncoding, spaceEncoding: SpaceEncoding, allowedCharacters: CharacterSet)
-+init URLEncodedFormEncoder(alphabetizeKeyValuePairs: Bool, arrayEncoding: ArrayEncoding, boolEncoding: BoolEncoding, dataEncoding: DataEncoding, dateEncoding: DateEncoding, keyEncoding: KeyEncoding, spaceEncoding: SpaceEncoding, allowedCharacters: CharacterSet)
-```
-
-</details>
-
-### swift-api-diagram
-
-`swift-api-diagram` generates a graph of APIs in [DOT format][dot]
+The `diagram` subcommand
+generates a graph of APIs in [DOT format][dot]
 that can be rendered by [GraphViz][graphviz] into a diagram.
 
 ```terminal
-$ swift run swift-api-diagram Alamofire/Source > graph.dot
+$ swift run swift-doc diagram Alamofire/Source > graph.dot
 $ head graph.dot
 digraph Anonymous {
   "Session" [shape=box];
@@ -266,6 +128,56 @@ Here's an excerpt of the graph generated for Alamofire:
 
 ![Excerpt of swift-doc-api Diagram for Alamofire](https://user-images.githubusercontent.com/7659/73189318-0db0e880-40d9-11ea-8895-341a75ce873c.png)
 
+## GitHub Action
+
+This repository also hosts a [GitHub Action][github actions]
+that you can incorporate into your project's workflow.
+
+The CommonMark files generated by `swift-doc`
+are formatted for publication to your project's [GitHub Wiki][github wiki],
+which you can do with
+[github-wiki-publish-action][github-wiki-publish-action].
+Alternatively,
+you could publish `swift-doc`-generated documentation to GitHub Pages,
+or bundle them into a release artifact.
+
+### Inputs
+
+- `inputs`:
+  One or more paths to Swift files in your workspace.
+  (Default: `"./Sources"`)
+- `output`:
+  The path for generated output.
+  (Default: `"./.build/documentation"`)
+
+### Example Workflow
+
+```yml
+# .github/workflows/documentation.yml
+name: Documentation
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Generate Documentation
+        uses: SwiftDocOrg/swift-doc@master
+        with:
+          inputs: "Source"
+          output: "Documentation"
+      - name: Upload Documentation to Wiki
+        uses: SwiftDocOrg/github-wiki-publish-action@master
+        with:
+          path: "Documentation"
+        env:
+          GITHUB_PERSONAL_ACCESS_TOKEN: ${{ secrets.GITHUB_PERSONAL_ACCESS_TOKEN }}
+```
+
+* * *
 
 ## Motivation