jazzy 0.13.7 → 0.14.2

data/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: .
   specs:
-    jazzy (0.13.7)
+    jazzy (0.14.2)
       cocoapods (~> 1.5)
       mustache (~> 1.1)
-      open4
+      open4 (~> 1.3)
       redcarpet (~> 3.4)
+      rexml (~> 3.2)
       rouge (>= 2.0.6, < 4.0)
       sassc (~> 2.1)
       sqlite3 (~> 1.3)
@@ -14,13 +15,15 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (3.0.3)
-    activesupport (5.2.6)
+    CFPropertyList (3.0.5)
+      rexml
+    activesupport (6.1.5)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-    addressable (2.7.0)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     algoliasearch (1.27.5)
       httpclient (~> 2.8, >= 2.8.3)
@@ -28,7 +31,7 @@ GEM
     ast (2.4.2)
     atomos (0.1.3)
     bacon (1.2.0)
-    claide (1.0.3)
+    claide (1.1.0)
     claide-plugins (0.9.2)
       cork
       nap
@@ -36,10 +39,10 @@ GEM
     clintegracon (0.7.0)
       colored (~> 1.2)
       diffy
-    cocoapods (1.10.1)
-      addressable (~> 2.6)
+    cocoapods (1.11.3)
+      addressable (~> 2.8)
       claide (>= 1.0.2, < 2.0)
-      cocoapods-core (= 1.10.1)
+      cocoapods-core (= 1.11.3)
       cocoapods-deintegrate (>= 1.0.3, < 2.0)
       cocoapods-downloader (>= 1.4.0, < 2.0)
       cocoapods-plugins (>= 1.0.0, < 2.0)
@@ -50,37 +53,37 @@ GEM
       escape (~> 0.0.4)
       fourflusher (>= 2.3.0, < 3.0)
       gh_inspector (~> 1.0)
-      molinillo (~> 0.6.6)
+      molinillo (~> 0.8.0)
       nap (~> 1.0)
-      ruby-macho (~> 1.4)
-      xcodeproj (>= 1.19.0, < 2.0)
-    cocoapods-core (1.10.1)
-      activesupport (> 5.0, < 6)
-      addressable (~> 2.6)
+      ruby-macho (>= 1.0, < 3.0)
+      xcodeproj (>= 1.21.0, < 2.0)
+    cocoapods-core (1.11.3)
+      activesupport (>= 5.0, < 7)
+      addressable (~> 2.8)
       algoliasearch (~> 1.0)
       concurrent-ruby (~> 1.1)
       fuzzy_match (~> 2.0.4)
       nap (~> 1.0)
       netrc (~> 0.11)
-      public_suffix
+      public_suffix (~> 4.0)
       typhoeus (~> 1.0)
-    cocoapods-deintegrate (1.0.4)
-    cocoapods-downloader (1.4.0)
+    cocoapods-deintegrate (1.0.5)
+    cocoapods-downloader (1.5.1)
     cocoapods-plugins (1.0.0)
       nap
-    cocoapods-search (1.0.0)
-    cocoapods-trunk (1.5.0)
+    cocoapods-search (1.0.1)
+    cocoapods-trunk (1.6.0)
       nap (>= 0.8, < 2.0)
       netrc (~> 0.11)
     cocoapods-try (1.2.0)
     colored (1.2)
     colored2 (3.1.2)
-    concurrent-ruby (1.1.8)
+    concurrent-ruby (1.1.9)
     cork (0.3.0)
       colored2 (~> 3.1)
     crack (0.4.5)
       rexml
-    danger (8.2.3)
+    danger (8.4.5)
       claide (~> 1.0)
       claide-plugins (>= 0.9.2)
       colored2 (~> 3.1)
@@ -95,107 +98,125 @@ GEM
       terminal-table (>= 1, < 4)
     diffy (3.4.0)
     escape (0.0.4)
-    ethon (0.14.0)
+    ethon (0.15.0)
       ffi (>= 1.15.0)
-    faraday (1.4.1)
+    faraday (1.10.0)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
       faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0)
+      faraday-multipart (~> 1.0)
       faraday-net_http (~> 1.0)
-      faraday-net_http_persistent (~> 1.1)
-      multipart-post (>= 1.2, < 3)
+      faraday-net_http_persistent (~> 1.0)
+      faraday-patron (~> 1.0)
+      faraday-rack (~> 1.0)
+      faraday-retry (~> 1.0)
       ruby2_keywords (>= 0.0.4)
+    faraday-em_http (1.0.0)
+    faraday-em_synchrony (1.0.0)
     faraday-excon (1.1.0)
     faraday-http-cache (2.2.0)
       faraday (>= 0.8)
+    faraday-httpclient (1.0.1)
+    faraday-multipart (1.0.3)
+      multipart-post (>= 1.2, < 3)
     faraday-net_http (1.0.1)
-    faraday-net_http_persistent (1.1.0)
-    ffi (1.15.0)
+    faraday-net_http_persistent (1.2.0)
+    faraday-patron (1.0.0)
+    faraday-rack (1.0.0)
+    faraday-retry (1.0.3)
+    ffi (1.15.5)
     fourflusher (2.3.1)
     fuzzy_match (2.0.4)
     gh_inspector (1.1.3)
-    git (1.8.1)
+    git (1.10.2)
       rchardet (~> 1.8)
     hashdiff (1.0.1)
     httpclient (2.8.3)
-    i18n (1.8.10)
+    i18n (1.10.0)
       concurrent-ruby (~> 1.0)
-    json (2.5.1)
+    json (2.6.1)
     kramdown (2.3.1)
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liferaft (0.0.6)
-    minitest (5.14.4)
-    mocha (1.12.0)
+    minitest (5.15.0)
+    mocha (1.13.0)
     mocha-on-bacon (0.2.3)
       mocha (>= 0.13.0)
-    molinillo (0.6.6)
+    molinillo (0.8.0)
     multipart-post (2.1.1)
     mustache (1.1.1)
     nanaimo (0.3.0)
     nap (1.1.0)
     netrc (0.11.0)
     no_proxy_fix (0.1.2)
-    octokit (4.21.0)
+    octokit (4.22.0)
       faraday (>= 0.9)
       sawyer (~> 0.8.0, >= 0.5.3)
     open4 (1.3.4)
-    parallel (1.20.1)
-    parser (2.7.2.0)
+    parallel (1.21.0)
+    parser (3.1.1.0)
       ast (~> 2.4.1)
-    powerpack (0.1.3)
     prettybacon (0.0.2)
       bacon (~> 1.2)
     public_suffix (4.0.6)
-    rainbow (2.2.2)
-      rake
-    rake (13.0.3)
+    rainbow (3.1.1)
+    rake (13.0.6)
     rchardet (1.8.0)
     redcarpet (3.5.1)
+    regexp_parser (2.2.1)
     rexml (3.2.5)
-    rouge (3.26.0)
-    rubocop (0.49.0)
+    rouge (3.28.0)
+    rubocop (1.26.0)
       parallel (~> 1.10)
-      parser (>= 2.3.3.1, < 3.0)
-      powerpack (~> 0.1)
-      rainbow (>= 1.99.1, < 3.0)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.16.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (~> 1.0, >= 1.0.1)
-    ruby-macho (1.4.0)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.16.0)
+      parser (>= 3.1.1.0)
+    ruby-macho (2.5.1)
     ruby-progressbar (1.11.0)
-    ruby2_keywords (0.0.4)
+    ruby2_keywords (0.0.5)
     sassc (2.4.0)
       ffi (~> 1.9)
     sawyer (0.8.2)
       addressable (>= 2.3.5)
       faraday (> 0.8, < 2.0)
     sqlite3 (1.4.2)
-    terminal-table (3.0.0)
-      unicode-display_width (~> 1.1, >= 1.1.1)
-    thread_safe (0.3.6)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
     typhoeus (1.4.0)
       ethon (>= 0.9.0)
-    tzinfo (1.2.9)
-      thread_safe (~> 0.1)
-    unicode-display_width (1.7.0)
-    webmock (3.12.2)
-      addressable (>= 2.3.6)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.1.0)
+    webmock (3.14.0)
+      addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
     xcinvoke (0.3.0)
       liferaft (~> 0.0.6)
-    xcodeproj (1.19.0)
+    xcodeproj (1.21.0)
       CFPropertyList (>= 2.3.3, < 4.0)
       atomos (~> 0.1.3)
       claide (>= 1.0.2, < 2.0)
       colored2 (~> 3.1)
       nanaimo (~> 0.3.0)
+      rexml (~> 3.2.4)
+    zeitwerk (2.5.4)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bacon
-  bundler (~> 1.7)
+  bundler (~> 2.1)
   clintegracon (= 0.7.0)
   danger
   diffy
@@ -204,8 +225,8 @@ DEPENDENCIES
   mocha-on-bacon
   prettybacon
   rake (~> 13.0)
-  rubocop (= 0.49.0)
+  rubocop (~> 1.18)
   webmock
 
 BUNDLED WITH
-   1.17.3
+   2.2.22

data/ObjectiveC.md

@@ -0,0 +1,208 @@
+This document is about Jazzy's Objective-C documentation generation.
+
+It's intended for users who are having problems after trying to follow the 
+examples in the [README](README.md#objective-c). It gives some solutions to
+common problems and explains how the system works to help users work through
+uncommon problems.
+
+* [How it works](#how-objective-c-docs-generation-works)
+* Common problems:
+    * [Apple SDK include failure](#problem-apple-sdk-importinclude-failure)
+    * [Non-SDK include failure](#problem-non-sdk-include-failure)
+    * [Argument list too long](#problem-argument-list-too-long-e2big-and-more)
+    * [Enum cases with wrong doc comment](#problem-enum-cases-have-the-wrong-doc-comment)
+    * [Swift API versions missing](#problem-swift-api-versions-are-all-missing)
+    * [Swift API versions use `Any`](#problem-swift-api-versions-have-any-instead-of-type-name)
+    * [Structural `NS_SWIFT_NAME` not working](#problem-structural-ns_swift_name-not-working)
+
+# How Objective-C docs generation works
+
+Jazzy uses `libclang` to generate docs for Objective-C projects. You can think
+of this as running some parts of the `clang` compiler against a header file.
+Jazzy refers to this header file as the _umbrella header_ but it does not have
+to be the umbrella header from a Clang module: it's just the header file that
+includes everything to be documented.
+
+This means there are two problems to solve:
+1. What `clang` flags are required; and
+2. How to pass them to the tools.
+
+Jazzy has two modes here: a smart mode that covers 90% of projects and a direct mode where the user provides all the flags.
+
+> *Important*: Jazzy does _not_ use any Objective-C build settings from your
+  Xcode project or `Package.swift`. If your project needs special settings
+  such as `#define`s then you need to repeat those in the Jazzy invocation.
+
+## Direct mode
+
+Passing a basic set of `clang` flags looks like this:
+
+```shell
+jazzy ...
+      --objc
+      --build-tool-arguments
+          --objc,MyProject/MyProject.h,--,-x,objective-c,
+          -isysroot,$(xcrun --show-sdk-path),
+          -I,$(pwd),
+          -fmodules
+```
+The `--build-tool-arguments` are arguments to `sourcekitten`. Everything after
+the `--` are the `clang` flags that will be used with the header file given 
+before the `--`.
+
+You can try these flags outside of Jazzy's environment:
+```shell
+clang -c -x objective-c -isysroot $(xcrun --show-sdk-path) -I $(pwd) MyProject/MyProject.h -fmodules
+```
+(The `-c` stops `clang` from trying to link an executable.)
+
+This is a good method of experimenting with compiler flags to get a working
+build without getting bogged down in the Jazzy and SourceKitten layers.
+
+## Smart mode
+
+The smart mode takes the variable parts of the basic set of flags and maps
+them from Jazzy flags:
+```shell
+jazzy ...
+      --objc
+      --umbrella-header MyProject/MyProject.h
+      --framework-root $(pwd)
+     [--sdk <sdk name>]
+```
+
+The `--umbrella-header` maps directly to the file passed to `sourcekitten`.
+
+The `--framework-root` is used for the `-I` include path, as well as every
+directory beneath it, recursively. So if your project structure looks like:
+```
+MyProject/
+         Sources/
+                Main/
+                Extension/
+```
+... and you pass `--framework-root MyProject`, then the `-I` flags passed to
+`clang` are `-I MyProject -I MyProject/Sources -I MyProject/Sources/Main -I
+MyProject/Sources/Extension`. This feature helps some projects resolve
+`#include` directives.
+
+Finally the `--sdk` option is passed through instead of the default `macosx` to
+find the SDK.
+
+## Mixing modes
+
+Do not mix modes. For example do not set both `--umbrella-header` and
+`--build-tool-arguments`. Jazzy does not flag this as an error for
+historical compatibility reasons, but the results are at best confusing.
+
+# Problem: Apple SDK import/include failure
+
+For example `fatal error: module 'UIKit' not found`.
+
+This means Jazzy is using the wrong SDK: the default is for macOS which does
+not have `UIKit`. Use `--sdk iphonesimulator`.
+
+# Problem: Non-SDK include failure
+
+For example `fatal error: 'MyModule/SomeHeader.h' file not found`.
+
+This means `clang` is not being passed the right flags to resolve a `#include` /
+`#import`.
+
+Start by finding the header file in the filesystem. You might be able to fix
+the problem just by adding extra `-I <path>` flags.
+
+Usually though the problem is that Xcode has done something clever that needs
+to be worked around or replicated.
+
+Xcode uses technology including Clang header maps to let files be found using
+lines like `#import <ModuleName/Header.h>` even when there is no such
+filesystem directory.
+
+To make the Jazzy build work you need to make these `#include`s work. The
+solution depends on your project structure. Some suggestions in rough order
+of complexity:
+* Use symlinks to create an equivalent directory tree. For example if
+  `Header.h` is inside `Sources/include` then symlink that directory to
+  `ModuleName` and pass `-I $(pwd)`.
+
+* Copy/link your header files into a throwaway directory tree that matches
+  the required structure and is used just for building docs.
+
+* Create a 'docs header file' separate to the framework's regular umbrella
+  header that contains only filesystem-correct `#import`s.
+
+* If you are happy to build the framework project before generating docs and
+  all the problematic paths have the form `ModuleName/PublicHeader.h` then
+  have `clang` resolve those includes to the built framework by passing
+  `-F <path of directory containing ModuleName.framework>`.
+
+* If you are happy to build the project before generating docs then you may
+  be able to use the header maps Xcode has generated. Check the build log in
+  Xcode to find them and the invocation syntax.
+
+* Manually construct an equivalent header map. This is complex not least
+  because Apple does not make tools or proper documentation available.
+  [An open-source starting point](https://milen.me/writings/swift-module-maps-vfs-overlays-header-maps/).
+
+# Problem: Argument list too long `E2BIG` (and more...)
+
+For example ``...open4.rb:49:in `exec': Argument list too long - [...]/bin/sourcekitten (Errno::E2BIG)``
+
+Can also manifest as 'generally weird' errors such as `sourcekitten` just
+crashing and `fatal error: could not build module 'Foundation'`.
+
+This means `--framework-root` is trying to add too many include directories:
+there are too many subdirectories of its parameter. If you cannot change this
+to something more specific that works then you need to use Jazzy's
+[direct mode](#direct-mode) to pass in the correct directories.
+
+# Problem: Enum cases have the wrong doc comment
+
+If you write an enum case with a doc comment followed by an enum case without
+a doc comment, then both get the same doc comment.
+
+This seems to be a bug in `libclang`. The only workaround is to add the missing
+doc comment.
+
+# Problem: Swift API versions are all missing
+
+This usually means the `clang` flags are malformed in a way that is ignored by
+`libclang` but not by the Swift Objective-C importer.
+
+One easy way to accidentally do this is passing `-I` without a path, for
+example `--build-tool-flags ...,-I,-I,Headers`,....
+
+This also sometimes happens if you are frequently switching back and forth
+between some Swift / Xcode versions -- it's a bug somewhere in the Apple tools.
+The bad state goes away with time / reboot.
+
+# Problem: Swift API versions have `Any` instead of type name
+
+Jazzy finds the Swift version of an Objective-C API using the SourceKit
+`source.request.editor.open.interface.header` request on the header file that
+contains the declaration, passing in the same `clang` flags used for the
+umbrella header. [See the code](https://github.com/jpsim/SourceKitten/blob/bed112c313ca8c3c149f8cb84069f1c080e86a7e/Source/SourceKittenFramework/Clang%2BSourceKitten.swift#L202).
+
+This means that each header file needs to compile standalone, without
+any implicit dependencies. For example:
+```
+ MyModule.h      // umbrella, includes MyClass.h then Utils.h
+    MyClass.h    // @interface MyClass ... @end
+    Utils.h      // void my_function( MyClass * myClass);
+```
+Here, `Utils.h` has an implicit dependency on `MyClass.h` that is normally
+satisfied by the include order of `MyModule.h`. One fix that allows `Utils.h`
+to compile standalone is to add `@class MyClass;`.
+
+# Problem: Structural `NS_SWIFT_NAME` not working
+
+The `NS_SWIFT_NAME` macro is mostly used to give an Objective-C API a
+different name in Swift. There are no known problems with this part.
+
+The macro can also be used to change the 'structure' of an API, for example
+make a C global function appear as a member function in Swift, or make a C
+class appear as a nested type in Swift.
+
+Jazzy doesn't understand or communicate these structural changes: you'll need
+to explain it in doc comments.

data/README.md

@@ -13,7 +13,7 @@ Instead of parsing your source files, `jazzy` hooks into [Clang][clang] and
 its comments for more accurate results. The output matches the look and feel
 of Apple’s official reference documentation, post WWDC 2014.
 
-Jazzy can also generate documentation from compiled swift modules [using their
+Jazzy can also generate documentation from compiled Swift modules [using their
 symbol graph](#docs-from-swiftmodules-or-frameworks) instead of source code.
 
 ![Screenshot](images/screenshot.jpg)
@@ -60,11 +60,14 @@ all available options, run `jazzy --help config`.
 ### Supported documentation keywords
 
 Swift documentation is written in markdown and supports a number of special keywords.
-For a complete list and examples, see Erica Sadun's post on [*Swift header documentation in Xcode 7*](https://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/),
-her [book on Swift Documentation Markup](https://itunes.apple.com/us/book/swift-documentation-markup/id1049010423), and the [Xcode Markup Formatting Reference](https://developer.apple.com/library/content/documentation/Xcode/Reference/xcode_markup_formatting_ref/).
+Here are some resources with tutorials and examples, starting with the most modern:
+* Apple's [Writing Symbol Documentation in Your Source Files](https://developer.apple.com/documentation/xcode/writing-symbol-documentation-in-your-source-files) article.
+* Apple's [Formatting Your Documentation Content](https://developer.apple.com/documentation/xcode/formatting-your-documentation-content) article.
+* Apple's [Xcode Markup Formatting Reference](https://developer.apple.com/library/content/documentation/Xcode/Reference/xcode_markup_formatting_ref/).
+* Erica Sadun's [Swift header documentation in Xcode 7](https://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/) post and her [book on Swift Documentation Markup](https://itunes.apple.com/us/book/swift-documentation-markup/id1049010423).
 
 For Objective-C documentation the same keywords are supported, but note that the format
-is slightly different. In Swift you would write `- returns:`, but in Objective-C you write `@return`. See Apple's [*HeaderDoc User Guide*](https://developer.apple.com/legacy/library/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html) for more details. **Note: `jazzy` currently does not support _all_ Objective-C keywords listed in this document, only @param, @return, @warning, @see, and @note.**
+is slightly different. In Swift you would write `- returns:`, but in Objective-C you write `@return`. See Apple's [*HeaderDoc User Guide*](https://developer.apple.com/legacy/library/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html) for more details. **Note: `jazzy` currently does not support _all_ Objective-C keywords listed in this document, only @param, @return, @warning, @see, @note, @code, @endcode, and @c.**
 
 Jazzy can also generate cross-references within your documentation. A symbol name in
 backticks generates a link, for example:
@@ -76,6 +79,12 @@ backticks generates a link, for example:
 * \`[MyClass method1]\` - a link to an Objective-C method.
 * \`-[MyClass method2:param1]\` - a link to another Objective-C method.
 
+Jazzy understands Apple's DocC-style links too, for example:
+* \`\`MyClass/method(param1:)\`\` - a link to the documentation for that method
+  that appears as just `method(param1:)` in the rendered page.
+* \`\`\<doc:method(_:)-e873\>\`\` - a link to a specific overload of `method(_:)`.
+  Jazzy can't tell which overload you intend and links to the first one.
+
 ### Math
 
 Jazzy can render math equations written in LaTeX embedded in your markdown:
@@ -108,8 +117,9 @@ jazzy \
   --clean \
   --author Realm \
   --author_url https://realm.io \
-  --github_url https://github.com/realm/realm-cocoa \
-  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
+  --source-host github \
+  --source-host-url https://github.com/realm/realm-cocoa \
+  --source-host-files-url https://github.com/realm/realm-cocoa/tree/v0.96.2 \
   --module-version 0.96.2 \
   --build-tool-arguments -scheme,RealmSwift \
   --module RealmSwift \
@@ -129,20 +139,36 @@ jazzy \
 
 ### Objective-C
 
-To generate documentation for Objective-C headers, you must pass the following
-parameters to jazzy:
-
+To generate documentation for a simple Objective-C project, you must pass the
+following parameters:
 * `--objc`
 * `--umbrella-header ...`
 * `--framework-root ...`
-* `--sdk [iphone|watch|appletv][os|simulator]|macosx` (optional, default value
+
+...and optionally:
+* `--sdk [iphone|watch|appletv][os|simulator]|macosx` (default value
    of `macosx`)
-* `--hide-declarations [objc|swift]` (optional, hides the selected language
-   declarations)
+* `--hide-declarations [objc|swift]` (hides the selected language declarations)
 
-##### Example
+For example, this is how the `AFNetworking` docs are generated:
+
+```shell
+jazzy \
+  --objc \
+  --author AFNetworking \
+  --author_url http://afnetworking.com \
+  --source-host github \
+  --source-host-url https://github.com/AFNetworking/AFNetworking \
+  --source-host-files-url https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
+  --module-version 2.6.2 \
+  --umbrella-header AFNetworking/AFNetworking.h \
+  --framework-root . \
+  --module AFNetworking
+```
 
-This is how Realm Objective-C docs are generated:
+For a more complicated Objective-C project, instead use `--build-tool-arguments`
+to pass arbitrary compiler flags.  For example, this is how Realm Objective-C
+docs are generated:
 
 ```shell
 jazzy \
@@ -150,8 +176,9 @@ jazzy \
   --clean \
   --author Realm \
   --author_url https://realm.io \
-  --github_url https://github.com/realm/realm-cocoa \
-  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v2.2.0 \
+  --source-host github \
+  --source-host-url https://github.com/realm/realm-cocoa \
+  --source-host-files-url https://github.com/realm/realm-cocoa/tree/v2.2.0 \
   --module-version 2.2.0 \
   --build-tool-arguments --objc,Realm/Realm.h,--,-x,objective-c,-isysroot,$(xcrun --show-sdk-path),-I,$(pwd) \
   --module Realm \
@@ -160,20 +187,8 @@ jazzy \
   --head "$(cat docs/custom_head.html)"
 ```
 
-This is how the AFNetworking docs are generated:
-
-```shell
-jazzy \
-  --objc \
-  --author AFNetworking \
-  --author_url http://afnetworking.com \
-  --github_url https://github.com/AFNetworking/AFNetworking \
-  --github-file-prefix https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
-  --module-version 2.6.2 \
-  --umbrella-header AFNetworking/AFNetworking.h \
-  --framework-root . \
-  --module AFNetworking
-```
+See [the Objective-C docs](ObjectiveC.md) for more information and some tips
+on troubleshooting.
 
 ### Mixed Objective-C / Swift
 
@@ -227,7 +242,7 @@ Some examples:
    ```shell
    jazzy --module Combine --swift-build-tool symbolgraph
          --sdk iphoneos
-         --build-tool-arguments --target,arm64-apple-ios14.1
+         --build-tool-arguments -target,arm64-apple-ios14.1
    ```
    The `target` is the LLVM target triple and needs to match the SDK.  The
    default here is the target of the host system that Jazzy is running on,
@@ -248,8 +263,16 @@ Some examples:
    This implies that `/Build/Products/MyMod.framework` exists and contains
    a `.swiftmodule`.  Again the `--source-directory` is searched by default
    if `-F` is not passed in.
-
-See `swift symbolgraph-extract --help` for all the things you can pass via
+5. With pre-generated symbolgraph files:
+    ```shell
+    jazzy --module MyMod --swift-build-tool symbolgraph
+          --symbolgraph-directory Build/symbolgraphs
+    ```
+    If you've separately generated symbolgraph files by the use of 
+    `-emit-symbol-graph`, you can pass the location of these files using
+    `--symbolgraph-directory` from where they can be parsed directly.
+
+See `swift symbolgraph-extract -help` for all the things you can pass via
 `--build-tool-arguments`: if your module has dependencies then you may need
 to add various search path options to let Swift load it.
 
@@ -306,6 +329,9 @@ In Swift mode, Jazzy by default documents only `public` and `open` declarations.
 include declarations with a lower access level, set the `--min-acl` flag to `internal`,
 `fileprivate`, or `private`.
 
+By default, Jazzy does not document declarations marked `@_spi` when `--min-acl` is
+set to `public` or `open`.  Set the `--include-spi-declarations` flag to include them.
+
 In Objective-C mode, Jazzy documents all declarations found in the `--umbrella-header`
 header file and any other header files included by it.
 
@@ -393,6 +419,10 @@ Check the `--min-acl` setting -- see [above](#controlling-what-is-documented).
    environment variable to point to the Xcode you want before running Jazzy
    without the `--swift-version` flag.
 
+### Objective-C
+
+See [this document](ObjectiveC.md).
+
 ### Installation Problems
 
 **Can't find header files / clang**