Merge branch 'master' into small-copy-edits-readme

Author: mattt

README.md

@@ -11,27 +11,44 @@ for each class, structure, enumeration, and protocol
 as well as top-level type aliases, functions, and variables.
 
 For an example of generated documentation,
-[check out the Wiki for our fork of Alamofire][alamofire wiki]. 
+[check out the Wiki for our fork of Alamofire][alamofire wiki].
 
 > **Note**:
 > Output is currently limited to CommonMark,
 > but the plan is to support HTML and other formats as well.
 
-## Usage
+## Command-Line Utility
 
-`swift-doc` can be used from the command-line 
-or in a [GitHub Actions][github actions] workflow.
+`swift-doc` can be used from the command-line on macOS and Linux.
 
-### Command-Line Utility
+### Installation
 
-To run `swift-doc` from the command-line,
-clone the repository
-and do `swift run swift-doc` from within the project directory.
+#### Homebrew
+
+Run the following command to install using [Homebrew](https://brew.sh/):
+
+```terminal
+$ brew install swiftdocorg/formulae/swift-doc
+```
+
+#### Manually
+
+Run the following commands to build and install manually:
 
 ```terminal
-$ git clone https://github.com/SwiftDocOrg/swift-doc.git
+$ git clone https://github.com/SwiftDocOrg/swift-doc
 $ cd swift-doc
-$ swift run swift-doc path/to/SwiftProject/Sources --output Documentation
+$ make install
+```
+
+### Usage
+
+`swift-doc` takes one or more paths and enumerates them recursively,
+collecting all Swift files into a single "module"
+and generating documentation accordingly.
+
+```terminal
+$ swift doc path/to/SwiftProject/Sources --output Documentation
 $ tree Documentation
 $ Documentation/
 ├── Home
@@ -40,36 +57,33 @@ $ Documentation/
 └── _Sidebar.md
 ```
 
-`swift-doc` takes one or more paths and enumerates them recursively,
-collecting all Swift files into a single "module"
-and generating documentation accordingly.
 By default,
 output files are written to `.build/documentation`,
 but you can change that with the `--output` option flag.
 
-### GitHub Action
+## 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` 
+The CommonMark files generated by `swift-doc`
 are formatted for publication to your project's [GitHub Wiki][github wiki],
-which you can do with 
+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
 
-- `inputs`: 
-  One or more paths to Swift files in your workspace. 
+- `inputs`:
+  One or more paths to Swift files in your workspace.
   (Default: `"./Sources"`)
 - `output`:
-  The path for generated output. 
+  The path for generated output.
   (Default: `"./.build/documentation"`)
 
-#### Example Workflow
+### Example Workflow
 
 ```yml
 name: Documentation
@@ -95,15 +109,15 @@ jobs:
           GITHUB_PERSONAL_ACCESS_TOKEN: ${{ secrets.GITHUB_PERSONAL_ACCESS_TOKEN }}
 ```
 
-* * *
+## Experimental Command-Line Tools
 
 In addition to `swift-doc`,
-this project currently ships with several, experimental executables
+this project currently ships with several, experimental tools
 that offer complementary functionality.
 It's unclear how everything will ultimately fit together,
-but for now, 
+but for now,
 they're incubating in a shared monorepo
-(the intent is for each of them to eventually become 
+(the intent is for each of them to eventually become
 an option, subcommand, or plugin of `swift-doc`).
 
 * * *
@@ -137,10 +151,10 @@ $ swift run swift-dcov SwiftSemantics/Sources/ | jq ".data.symbols[] | select(.d
 While there are plenty of tools for assessing test coverage for code,
 we weren't able to find anything analogous for documentation coverage.
 To this end,
-we've contrived a simple JSON format 
+we've contrived a simple JSON format
 [inspired by llvm-cov](https://reviews.llvm.org/D22651#change-xdePaVfBugps).
 
-If you know of an existing standard 
+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]!
 
@@ -169,7 +183,7 @@ you can feed the output of `swift-api-inventory` to conventional diffing tools
 to determine API changes between different releases of a project.
 
 For example,
-here's an API diff between the first beta and latest release candidate of 
+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
@@ -231,7 +245,7 @@ digraph Anonymous {
   "URLEncodedFormEncoder" [shape=box,peripheries=2];
   "ServerTrustManager" [shape=box];
   "MultipartFormData" [shape=box];
-  
+
   subgraph cluster_Request {
     "DataRequest" [shape=box];
     "Request" [shape=box];
@@ -253,13 +267,13 @@ for both Swift and Objective-C projects.
 Over time, however,
 the way we write Swift code —
 and indeed the language itself —
-has evolved to incorporate patterns and features 
-that are difficult to understand using 
+has evolved to incorporate patterns and features
+that are difficult to understand using
 the same documentation standards that served us well for Objective-C.
 
 Whereas in Objective-C,
 you could get a complete view of a type's functionality from its class hierarchy,
-Swift code today tends to layer and distribute functionality across 
+Swift code today tends to layer and distribute functionality across
 [a network of types][swift number protocols diagram].
 While adopting a
 [protocol-oriented paradigm][protocol-oriented programming]
@@ -271,7 +285,7 @@ is to make Swift documentation more useful
 by surfacing the information you need to understand how an API works
 and presenting it in a way that can be easily searched and accessed.
 We want developers to be empowered to use Swift packages to their full extent,
-without being reliant on (often outdated) blog posts or Stack Overflow threads. 
+without being reliant on (often outdated) blog posts or Stack Overflow threads.
 We want documentation coverage to become as important as test coverage:
 a valuable metric for code quality,
 and an expected part of first-rate open source projects.
@@ -294,8 +308,10 @@ having instead focused on perceived cosmetic issues.)
 Without much in the way of strong design guidance,
 we're not entirely sure what Swift documentation _should_ look like.
 But we do think plain text is a good place to start.
-We look forward to soliciting feedback and ideas from everyone
-to identify what those needs are and coming up with the best ways to meet them.
+We look forward to 
+soliciting feedback and ideas from everyone 
+so that we can identify those needs 
+and figure out the best ways to meet them.
 
 In the meantime,
 we've set ourselves up for success
@@ -320,7 +336,7 @@ Because it relies only on a syntactic reading of Swift source code,
 without needing code first to be compiled,
 `swift-doc` is quite fast.
 As a baseline,
-compare its performance to Jazzy 
+compare its performance to Jazzy
 when generating documentation for [SwiftSemantics][swiftsemantics]:
 
 ```terminal
@@ -347,17 +363,19 @@ to [a GitHub wiki generated with `swift-doc`][swift-doc swiftsemantics].
 
 ## What About [SwiftDoc.org][swiftdoc.org]?
 
-**tl;dr:** 
-We're currently working on updating SwiftDoc.org for Swift 5,
-and hope to have it released later this week.
+**tl;dr:**
+SwiftDoc.org is now updated for Swift 5.1,
+but we're still working to migrate over a few missing parts
+(notably, the beloved
+[type inheritance graphs](https://swiftdoc.org/v4.2/protocol/expressiblebyfloatliteral/hierarchy/)).
 
 SwiftDoc.org,
 [originally "Swifter"](http://natecook.com/blog/2014/09/introducing-swifter/),
-was created by Nate Cook ([@natecook1000][@natecook1000]) 
+was created by Nate Cook ([@natecook1000][@natecook1000])
 in September 2014.
 At the time,
 Swift tooling was still in its infancy,
-so Nate actually 
+so Nate actually
 [wrote a parser (from scratch!)](https://github.com/SwiftDocOrg/swiftdoc-parser)
 to pull symbols and documentation from the Swift standard library.
 Nate became managing editor of [NSHipster][nshipster] in 2015,
@@ -369,9 +387,9 @@ After the hand-off,
 we were able to get the site updated for Swift 4.2 without too much trouble.
 But when it came time to regenerate the site for Swift 5,
 we found ourselves deep in ["dependency hell"][dependency hell]
-(something to do with the [regular expression][pcre] library 
+(something to do with the [regular expression][pcre] library
 that Nate had used for the parser).
-After begging and pleading with 
+After begging and pleading with
 the spirits possessing our `node_modules` directory to no avail,
 we decided to roll up our sleeves and get started on a long-term replacement —
 this time, written in Swift.