jazzy 0.14.1 → 0.14.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f55576dbfb09517321b17ea90b50e672c8ad6c50c563e087b381849ed2f7445
-  data.tar.gz: 9a5c54d86a73cf125109bd87a0f669c9807b419aa41f54174544d3ebd86632d2
+  metadata.gz: e5d4f36fe547b9d232250c291bde5c20c12132335609b7de4e7cb39af6e2586c
+  data.tar.gz: 2c310fd944aa0cdd6565f6af00bf303526d392ed6d41626da2eb89c95222330b
 SHA512:
-  metadata.gz: 61f70f156605dacf0b066262b7ccf694902117ce483fc056fa669af232530a7da180ed70134e1c0b8570f8ad55228c3324b53007e6f9d0519fe306977bd40b1e
-  data.tar.gz: 7655c01fd0c0bc9113b532b2e0531e56faf0aa00a5815a9713ca35b4cfa1fb45c391f6b77b4cd8501bce34ed4617c84dc1e2e436afda7bf8721d715ddb917d70
+  metadata.gz: 2994093e3bfcf803a5479b9d9fe2132f0b26027d11d0ca44754aa0a6b8af1ebbdd1fd0838efa42bacc921ac81286c041294195f1c2d39b092162deccce0d5ab1
+  data.tar.gz: 98a0573749bbd37464e910b9d22fe98d0dfd3804f26f313b1d9b743d39c4dd023fbbb793316ce08a20168f18c5b8242a3f4b5216bdbcaeffbda27615cb67b699

data/.github/workflows/Tests.yml

@@ -15,14 +15,14 @@ jobs:
         with:
           ruby-version: 2.6
           bundler-cache: true
+      - name: Rubocop
+        run: |
+          bundle exec rake rubocop
       - name: Danger
         env:
           DANGER_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           bundle exec danger --verbose
-      - name: Rubocop
-        run: |
-          bundle exec rake rubocop
 
   spec:
     runs-on: macos-11
@@ -31,7 +31,7 @@ jobs:
       matrix:
         spec: ["objc_spec", "swift_spec", "cocoapods_spec"]
     env:
-      DEVELOPER_DIR: /Applications/Xcode_13.0.app/Contents/Developer
+      DEVELOPER_DIR: /Applications/Xcode_13.2.app/Contents/Developer
     steps:
       - uses: actions/checkout@v2
         with:

data/.rubocop.yml

@@ -7,10 +7,12 @@ AllCops:
   SuggestExtensions: false
   TargetRubyVersion: 2.6
 
-#- Pending Cops as of 1.22.0 ---------------------------------------------#
+#- Pending Cops as of 1.26.0 ---------------------------------------------#
 
 Gemspec/DateAssignment: # (new in 1.10)
   Enabled: true
+Gemspec/RequireMFA: # new in 1.23
+  Enabled: true
 Layout/SpaceBeforeBrackets: # (new in 1.7)
   Enabled: true
 Lint/AmbiguousAssignment: # (new in 1.7)
@@ -53,6 +55,10 @@ Lint/UnexpectedBlockArity: # (new in 1.5)
   Enabled: true
 Lint/UnmodifiedReduceAccumulator: # (new in 1.1)
   Enabled: true
+Lint/UselessRuby2Keywords: # new in 1.23
+  Enabled: true
+Naming/BlockForwarding: # new in 1.24
+  Enabled: true
 Naming/InclusiveLanguage: # (new in 1.18)
   Enabled: true
 Security/IoMethods: # new in 1.22
@@ -65,6 +71,10 @@ Style/DocumentDynamicEvalDefinition: # (new in 1.1)
   Enabled: true
 Style/EndlessMethod: # (new in 1.8)
   Enabled: true
+Style/FileRead: # new in 1.24
+  Enabled: true
+Style/FileWrite: # new in 1.24
+  Enabled: true
 Style/HashConversion: # (new in 1.10)
   Enabled: true
 Style/HashExcept: # (new in 1.7)
@@ -73,16 +83,22 @@ Style/IfWithBooleanLiteralBranches: # (new in 1.9)
   Enabled: true
 Style/InPatternThen: # (new in 1.16)
   Enabled: true
+Style/MapToHash: # new in 1.24
+  Enabled: true
 Style/MultilineInPatternThen: # (new in 1.16)
   Enabled: true
 Style/NegatedIfElseCondition: # (new in 1.2)
   Enabled: true
+Style/NestedFileDirname: # new in 1.26
+  Enabled: true
 Style/NilLambda: # (new in 1.3)
   Enabled: true
 Style/NumberedParameters: # new in 1.22
   Enabled: true
 Style/NumberedParametersLimit: # new in 1.22
   Enabled: true
+Style/OpenStructUse: # new in 1.23
+  Enabled: true
 Style/QuotedSymbols: # (new in 1.16)
   Enabled: true
 Style/RedundantArgument: # (new in 1.4)

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 0.14.2
+
+##### Breaking
+
+* When building with Swift 5.6 and not passing `—-module` to Jazzy, declarations
+  may not be correctly identified as undocumented and docs may include unwanted
+  extensions.  Pass `—-module MyModuleName` to fix this.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+##### Enhancements
+
+* Support using pre-generated symbolgraph files in Swift symbolgraph mode.  
+  [Nathan Wong](https://github.com/esteluk)
+
+* Issue a warning on some combinations of Objective-C flags.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#900](https://github.com/realm/jazzy/issues/900)
+
+* Support Swift 5.6.  The bundled `sourcekitten` is a universal binary.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+##### Bug Fixes
+
+* In Swift symbolgraph mode, stop including extensions to types that are beneath
+  the minimum ACL.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1291](https://github.com/realm/jazzy/issues/1291)
+
 ## 0.14.1
 
 ##### Breaking

data/CONTRIBUTING.md

@@ -49,7 +49,7 @@ git push
 You'll need push access to the integration specs repo to do this. You can
 request access from one of the maintainers when filing your PR.
 
-You must have Xcode 13 installed to build the integration specs.
+You must have Xcode 13.2 installed to build the integration specs.
 
 ## Making changes to SourceKitten
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.14.1)
+    jazzy (0.14.2)
       cocoapods (~> 1.5)
       mustache (~> 1.1)
       open4 (~> 1.3)
@@ -15,9 +15,9 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (3.0.4)
+    CFPropertyList (3.0.5)
       rexml
-    activesupport (6.1.4.1)
+    activesupport (6.1.5)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -31,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
@@ -39,10 +39,10 @@ GEM
     clintegracon (0.7.0)
       colored (~> 1.2)
       diffy
-    cocoapods (1.11.2)
+    cocoapods (1.11.3)
       addressable (~> 2.8)
       claide (>= 1.0.2, < 2.0)
-      cocoapods-core (= 1.11.2)
+      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)
@@ -57,7 +57,7 @@ GEM
       nap (~> 1.0)
       ruby-macho (>= 1.0, < 3.0)
       xcodeproj (>= 1.21.0, < 2.0)
-    cocoapods-core (1.11.2)
+    cocoapods-core (1.11.3)
       activesupport (>= 5.0, < 7)
       addressable (~> 2.8)
       algoliasearch (~> 1.0)
@@ -83,7 +83,7 @@ GEM
       colored2 (~> 3.1)
     crack (0.4.5)
       rexml
-    danger (8.4.0)
+    danger (8.4.5)
       claide (~> 1.0)
       claide-plugins (>= 0.9.2)
       colored2 (~> 3.1)
@@ -98,18 +98,19 @@ 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.8.0)
+    faraday (1.10.0)
       faraday-em_http (~> 1.0)
       faraday-em_synchrony (~> 1.0)
       faraday-excon (~> 1.1)
-      faraday-httpclient (~> 1.0.1)
+      faraday-httpclient (~> 1.0)
+      faraday-multipart (~> 1.0)
       faraday-net_http (~> 1.0)
-      faraday-net_http_persistent (~> 1.1)
+      faraday-net_http_persistent (~> 1.0)
       faraday-patron (~> 1.0)
       faraday-rack (~> 1.0)
-      multipart-post (>= 1.2, < 3)
+      faraday-retry (~> 1.0)
       ruby2_keywords (>= 0.0.4)
     faraday-em_http (1.0.0)
     faraday-em_synchrony (1.0.0)
@@ -117,27 +118,30 @@ GEM
     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.2.0)
     faraday-patron (1.0.0)
     faraday-rack (1.0.0)
-    ffi (1.15.4)
+    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.9.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)
+    minitest (5.15.0)
     mocha (1.13.0)
     mocha-on-bacon (0.2.3)
       mocha (>= 0.13.0)
@@ -148,34 +152,34 @@ GEM
     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.21.0)
-    parser (3.0.2.0)
+    parser (3.1.1.0)
       ast (~> 2.4.1)
     prettybacon (0.0.2)
       bacon (~> 1.2)
     public_suffix (4.0.6)
-    rainbow (3.0.0)
+    rainbow (3.1.1)
     rake (13.0.6)
     rchardet (1.8.0)
     redcarpet (3.5.1)
-    regexp_parser (2.1.1)
+    regexp_parser (2.2.1)
     rexml (3.2.5)
-    rouge (3.26.1)
-    rubocop (1.22.0)
+    rouge (3.28.0)
+    rubocop (1.26.0)
       parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+      parser (>= 3.1.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.12.0, < 2.0)
+      rubocop-ast (>= 1.16.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.12.0)
-      parser (>= 3.0.1.1)
+    rubocop-ast (1.16.0)
+      parser (>= 3.1.1.0)
     ruby-macho (2.5.1)
     ruby-progressbar (1.11.0)
     ruby2_keywords (0.0.5)
@@ -205,7 +209,7 @@ GEM
       colored2 (~> 3.1)
       nanaimo (~> 0.3.0)
       rexml (~> 3.2.4)
-    zeitwerk (2.4.2)
+    zeitwerk (2.5.4)
 
 PLATFORMS
   ruby

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

@@ -67,7 +67,7 @@ Here are some resources with tutorials and examples, starting with the most mode
 * 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:
@@ -139,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 \
@@ -171,21 +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 \
-  --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
-```
+See [the Objective-C docs](ObjectiveC.md) for more information and some tips
+on troubleshooting.
 
 ### Mixed Objective-C / Swift
 
@@ -260,6 +263,14 @@ 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.
+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
@@ -408,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**

data/Rakefile

@@ -105,10 +105,12 @@ begin
   desc 'Vendors SourceKitten'
   task :sourcekitten do
     sk_dir = 'SourceKitten'
-    Dir.chdir(sk_dir) do
-      `swift build -c release`
+    bin_path = Dir.chdir(sk_dir) do
+      build_cmd = 'swift build -c release --arch arm64 --arch x86_64'
+      `#{build_cmd}`
+      `#{build_cmd} --show-bin-path`.chomp
     end
-    FileUtils.cp_r "#{sk_dir}/.build/release/sourcekitten", 'bin'
+    FileUtils.cp_r "#{bin_path}/sourcekitten", 'bin'
   end
 
   #-- Theme Dependencies -----------------------------------------------------#

data/jazzy.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ['jp@jpsim.com']
   spec.summary       = 'Soulful docs for Swift & Objective-C.'
   spec.description   = 'Soulful docs for Swift & Objective-C. ' \
-    "Run in your Xcode project's root directory for " \
+    "Run in your SPM or Xcode project's root directory for " \
     'instant HTML docs.'
   spec.homepage      = 'https://github.com/realm/jazzy'
   spec.license       = 'MIT'
@@ -32,4 +32,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 13.0'
 
   spec.required_ruby_version = '>= 2.6.3'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/jazzy/config.rb

@@ -193,6 +193,12 @@ module Jazzy
       default: Pathname.pwd,
       parse: ->(sd) { expand_path(sd) }
 
+    config_attr :symbolgraph_directory,
+      command_line: '--symbolgraph-directory DIRPATH',
+      description: 'A directory containing a set of Swift Symbolgraph files ' \
+        'representing the module to be documented',
+      parse: ->(sd) { expand_path(sd) }
+
     config_attr :excluded_files,
       command_line: ['-e', '--exclude filepath1,filepath2,…filepathN', Array],
       description: 'Source file pathnames to be excluded from documentation. '\
@@ -591,6 +597,13 @@ module Jazzy
         warning 'Option `source_host` is set but has no effect without either '\
           '`source_host_url` or `source_host_files_url`.'
       end
+
+      if objc_mode &&
+         build_tool_arguments_configured &&
+         (framework_root_configured || umbrella_header_configured)
+        warning 'Option `build_tool_arguments` is set: values passed to '\
+          '`framework_root` or `umbrella_header` may be ignored.'
+      end
     end
 
     # rubocop:enable Metrics/MethodLength

data/lib/jazzy/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jazzy
-  VERSION = '0.14.1' unless defined? Jazzy::VERSION
+  VERSION = '0.14.2' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/highlighter.rb

@@ -2,18 +2,6 @@
 
 require 'rouge'
 
-# While Rouge is downlevel (Rouge PR#1715 unreleased)
-module Rouge
-  module Lexers
-    class Swift
-      prepend :root do
-        rule(/\b(?:async|await|isolated)\b/, Keyword)
-        rule(/\b(?:actor|nonisolated)\b/, Keyword::Declaration)
-      end
-    end
-  end
-end
-
 module Jazzy
   # This module helps highlight code
   module Highlighter

data/lib/jazzy/search_builder.rb

@@ -6,17 +6,15 @@ module Jazzy
       decls = source_module.all_declarations.select do |d|
         d.type && d.name && !d.name.empty?
       end
-      index = decls.map do |d|
+      index = decls.to_h do |d|
         [d.url,
          {
            name: d.name,
            abstract: d.abstract && d.abstract.split(/\n/).map(&:strip).first,
-           parent_name: d.parent_in_code && d.parent_in_code.name,
+           parent_name: d.parent_in_code&.name,
          }.reject { |_, v| v.nil? || v.empty? }]
-      end.to_h
-      File.open(File.join(output_dir, 'search.json'), 'w') do |f|
-        f.write(index.to_json)
       end
+      File.write(File.join(output_dir, 'search.json'), index.to_json)
     end
   end
 end

data/lib/jazzy/source_declaration.rb

@@ -183,10 +183,12 @@ module Jazzy
       inherited_types.any? { |t| !unwanted.include?(t) }
     end
 
-    # SourceKit only sets modulename for imported modules
+    # Pre-Swift 5.6: SourceKit only sets modulename for imported modules
+    # Swift 5.6+: modulename is always set
     def type_from_doc_module?
       !type.extension? ||
-        (swift? && usr && modulename.nil?)
+        (swift? && usr &&
+          (modulename.nil? || modulename == Config.instance.module_name))
     end
 
     # Info text for contents page by collapsed item name

data/lib/jazzy/sourcekitten.rb

@@ -355,7 +355,9 @@ module Jazzy
     # Call things undocumented if they were compiled properly
     # and came from our module.
     def self.should_mark_undocumented(declaration)
-      declaration.usr && !declaration.modulename
+      declaration.usr &&
+        (declaration.modulename.nil? ||
+         declaration.modulename == Config.instance.module_name)
     end
 
     def self.process_undocumented_token(doc, declaration)

data/lib/jazzy/symbol_graph.rb

@@ -14,27 +14,24 @@ require 'jazzy/symbol_graph/ext_node'
 
 module Jazzy
   module SymbolGraph
-    # Run `swift symbolgraph-extract` with configured args,
-    # parse the results, and return as JSON in SourceKit[ten]
+    # Find swift symbol graph files, either having been passed
+    # in directly, or generated by running`swift symbolgraph-extract`
+    # with configured args.
+    # Then parse the results, and return as JSON in SourceKit[ten]
     # format.
     def self.build(config)
-      Dir.mktmpdir do |tmp_dir|
-        args = arguments(config, tmp_dir)
+      if config.symbolgraph_directory.nil?
+        Dir.mktmpdir do |tmp_dir|
+          args = arguments(config, tmp_dir)
 
-        Executable.execute_command('swift',
-                                   args.unshift('symbolgraph-extract'),
-                                   true) # raise on error
+          Executable.execute_command('swift',
+                                     args.unshift('symbolgraph-extract'),
+                                     true) # raise on error
 
-        Dir[tmp_dir + '/*.symbols.json'].map do |filename|
-          # The @ part is for extensions in our module (before the @)
-          # of types in another module (after the @).
-          filename =~ /(.*?)(@(.*?))?\.symbols/
-          module_name = Regexp.last_match[3] || Regexp.last_match[1]
-          {
-            filename =>
-              Graph.new(File.read(filename), module_name).to_sourcekit,
-          }
-        end.to_json
+          parse_symbols(tmp_dir)
+        end
+      else
+        parse_symbols(config.symbolgraph_directory.to_s)
       end
     end
 
@@ -69,6 +66,20 @@ module Jazzy
       args + config.build_tool_arguments
     end
 
+    # Parse the symbol files in the given directory
+    def self.parse_symbols(directory)
+      Dir[directory + '/*.symbols.json'].map do |filename|
+        # The @ part is for extensions in our module (before the @)
+        # of types in another module (after the @).
+        File.basename(filename) =~ /(.*?)(@(.*?))?\.symbols/
+        module_name = Regexp.last_match[3] || Regexp.last_match[1]
+        {
+          filename =>
+            Graph.new(File.read(filename), module_name).to_sourcekit,
+        }
+      end.to_json
+    end
+
     # Get the SDK path.  On !darwin this just isn't needed.
     def self.sdk(config)
       `xcrun --show-sdk-path --sdk #{config.sdk}`.chomp

data/spec/integration_spec.rb

@@ -85,9 +85,8 @@ CLIntegracon.configure do |c|
 
   # Transform produced databases to csv
   c.transform_produced '**/*.dsidx' do |path|
-    File.open("#{path}.csv", 'w') do |file|
-      file.write `sqlite3 -header -csv #{path} "select * from searchIndex;"`
-    end
+    File.write("#{path}.csv",
+               `sqlite3 -header -csv #{path} "select * from searchIndex;"`)
   end
   # Now that we're comparing the CSV, we don't care about the binary
   c.ignores '**/*.dsidx'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazzy
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.14.2
 platform: ruby
 authors:
 - JP Simard
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-02 00:00:00.000000000 Z
+date: 2022-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocoapods
@@ -173,8 +173,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Soulful docs for Swift & Objective-C. Run in your Xcode project's root
-  directory for instant HTML docs.
+description: Soulful docs for Swift & Objective-C. Run in your SPM or Xcode project's
+  root directory for instant HTML docs.
 email:
 - jp@jpsim.com
 executables:
@@ -192,6 +192,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
+- ObjectiveC.md
 - README.md
 - Rakefile
 - bin/jazzy
@@ -354,7 +355,8 @@ files:
 homepage: https://github.com/realm/jazzy
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: