jazzy 0.14.3 → 0.14.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e164bb425f5dbce55a0705ce07038b3b34fd5a055dd1a6d309250665cabb25f
-  data.tar.gz: 770f2055c954dfea38085151f571669be2013458f370556808f165b537fc4cf9
+  metadata.gz: 46b23a5fd216d0d68d6d48b094669c92fbbccdca52e5a7923a11429a9bdca958
+  data.tar.gz: 3d16963bbb5e8dac679125d548ba3652e45bd42354b151c9886006f2fa86d82c
 SHA512:
-  metadata.gz: a1d8ffd5b6bc1ed5637698a73c18918989105486d1da0198ba35450c7b9943802eaa4e5e31dde0d6fdaa54a6472fca85a8dbbbb3367db4be0de7a1ff80123333
-  data.tar.gz: c63d5645be9de11716c7b301bdc196749afdb841719010dc3a20f15ec3380a3acf61b220b976b4c5247f22a1368b4db9f6d1b4ff67a81d76c312e9f6c8be8964
+  metadata.gz: 9cb4e55db01ae8d541128f97bce1470f5c5b133e4925c24cacb3c234c242ed7978c23f94fb16f35e92455696ea9b012c914e7db4019e001de68eebcb016f1dc7
+  data.tar.gz: 0aa0c110530795c1c30a7b4c6f3ca4378fb9c40f5740c48ef3c04a6fb14e52f5daf39f1be0335d351902e94b23034b0b7ad29a01ae56ae262303245b44e63469

data/.github/workflows/Tests.yml

@@ -10,10 +10,10 @@ jobs:
   danger_and_rubocop:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.6
+          ruby-version: 3.2
           bundler-cache: true
       - name: Rubocop
         run: |
@@ -25,23 +25,23 @@ jobs:
           bundle exec danger --verbose
 
   spec:
-    runs-on: macos-12
+    runs-on: macos-13
     continue-on-error: true
     strategy:
       matrix:
         spec: ["objc_spec", "swift_spec", "cocoapods_spec"]
     env:
-      DEVELOPER_DIR: /Applications/Xcode_14.0.app/Contents/Developer
+      DEVELOPER_DIR: /Applications/Xcode_15.0.app/Contents/Developer
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           submodules: recursive
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.6
+          ruby-version: 3.2
           bundler-cache: true
       - name: Cache cocoapods
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         env:
           cache-name: cocoapods
         with:

data/.rubocop.yml

@@ -1,16 +1,19 @@
 AllCops:
   Exclude:
     - ./spec/integration_specs/**/*
+    - ./spec/Moya.podspec
     - ./vendor/**/*
     - ./tmp/**/*
     - ./SourceKitten/**/*
   SuggestExtensions: false
   TargetRubyVersion: 2.6
 
-#- Pending Cops as of 1.36.0 ---------------------------------------------#
+#- Pending Cops as of 1.56.3 ---------------------------------------------#
 
 Gemspec/DeprecatedAttributeAssignment: # new in 1.30
   Enabled: true
+Gemspec/DevelopmentDependencies: # new in 1.44
+  Enabled: false
 Gemspec/RequireMFA: # new in 1.23
   Enabled: true
 Layout/LineContinuationLeadingSpace: # new in 1.31
@@ -29,6 +32,10 @@ Lint/DeprecatedConstants: # (new in 1.8)
   Enabled: true
 Lint/DuplicateBranch: # (new in 1.3)
   Enabled: true
+Lint/DuplicateMagicComment: # new in 1.37
+  Enabled: true
+Lint/DuplicateMatchPattern: # new in 1.50
+  Enabled: true
 Lint/DuplicateRegexpCharacterClassElement: # (new in 1.1)
   Enabled: true
 Lint/EmptyBlock: # (new in 1.1)
@@ -41,6 +48,8 @@ Lint/IncompatibleIoSelectWithFiberScheduler: # new in 1.21
   Enabled: true
 Lint/LambdaWithoutLiteralBlock: # (new in 1.8)
   Enabled: true
+Lint/MixedCaseRange: # new in 1.53
+  Enabled: true
 Lint/NonAtomicFileOperation: # new in 1.31
   Enabled: true
 Lint/NoReturnInBeginEndBlocks: # (new in 1.2)
@@ -51,6 +60,8 @@ Lint/OrAssignmentToConstant: # (new in 1.9)
   Enabled: true
 Lint/RedundantDirGlobSort: # (new in 1.8)
   Enabled: true
+Lint/RedundantRegexpQuantifiers: # new in 1.53
+  Enabled: true
 Lint/RefinementImportMethods: # new in 1.27
   Enabled: true
 Lint/RequireRangeParentheses: # new in 1.32
@@ -67,20 +78,34 @@ Lint/UnexpectedBlockArity: # (new in 1.5)
   Enabled: true
 Lint/UnmodifiedReduceAccumulator: # (new in 1.1)
   Enabled: true
+Lint/UselessRescue: # new in 1.43
+  Enabled: true
 Lint/UselessRuby2Keywords: # new in 1.23
   Enabled: true
+Metrics/CollectionLiteralLength: # new in 1.47
+  Enabled: true
 Naming/BlockForwarding: # new in 1.24
   Enabled: true
 Naming/InclusiveLanguage: # (new in 1.18)
   Enabled: true
 Security/CompoundHash: # new in 1.28
   Enabled: true
+Style/ConcatArrayLiterals: # new in 1.41
+  Enabled: true
 Security/IoMethods: # new in 1.22
   Enabled: true
 Style/ArgumentsForwarding: # (new in 1.1)
   Enabled: true
+Style/ArrayIntersect: # new in 1.40
+  Enabled: true
 Style/CollectionCompact: # (new in 1.2)
   Enabled: true
+Style/ComparableClamp: # new in 1.44
+  Enabled: true
+Style/DataInheritance: # new in 1.49
+  Enabled: true
+Style/DirEmpty: # new in 1.48
+  Enabled: true
 Style/DocumentDynamicEvalDefinition: # (new in 1.1)
   Enabled: true
 Style/EmptyHeredoc: # new in 1.32
@@ -89,8 +114,12 @@ Style/EndlessMethod: # (new in 1.8)
   Enabled: true
 Style/EnvHome: # new in 1.29
   Enabled: true
+Style/ExactRegexpMatch: # new in 1.51
+  Enabled: true
 Style/FetchEnvVar: # new in 1.28
   Enabled: true
+Style/FileEmpty: # new in 1.48
+  Enabled: true
 Style/FileRead: # new in 1.24
   Enabled: true
 Style/FileWrite: # new in 1.24
@@ -109,6 +138,10 @@ Style/MapCompactWithConditionalBlock: # new in 1.30
   Enabled: true
 Style/MapToHash: # new in 1.24
   Enabled: true
+Style/MapToSet: # new in 1.42
+  Enabled: true
+Style/MinMaxComparison: # new in 1.42
+  Enabled: true
 Style/MultilineInPatternThen: # (new in 1.16)
   Enabled: true
 Style/NegatedIfElseCondition: # (new in 1.2)
@@ -125,20 +158,48 @@ Style/ObjectThen: # new in 1.28
   Enabled: true
 Style/OpenStructUse: # new in 1.23
   Enabled: true
+Style/OperatorMethodCall: # new in 1.37
+  Enabled: true
 Style/QuotedSymbols: # (new in 1.16)
   Enabled: true
 Style/RedundantArgument: # (new in 1.4)
   Enabled: true
+Style/RedundantArrayConstructor: # new in 1.52
+  Enabled: true
+Style/RedundantConstantBase: # new in 1.40
+  Enabled: true
+Style/RedundantCurrentDirectoryInPath: # new in 1.53
+  Enabled: true
+Style/RedundantDoubleSplatHashBraces: # new in 1.41
+  Enabled: true
+Style/RedundantEach: # new in 1.38
+  Enabled: true
+Style/RedundantFilterChain: # new in 1.52
+  Enabled: true
+Style/RedundantHeredocDelimiterQuotes: # new in 1.45
+  Enabled: true
 Style/RedundantInitialize: # new in 1.27
   Enabled: true
+Style/RedundantLineContinuation: # new in 1.49
+  Enabled: true
+Style/RedundantRegexpArgument: # new in 1.53
+  Enabled: true
+Style/RedundantRegexpConstructor: # new in 1.52
+  Enabled: true
 Style/RedundantSelfAssignmentBranch: # (new in 1.19)
   Enabled: true
+Style/RedundantStringEscape: # new in 1.37
+  Enabled: true
+Style/ReturnNilInPredicateMethodDefinition: # new in 1.53
+  Enabled: true
 Style/SelectByRegexp: # new in 1.22
   Enabled: true
 Style/StringChars: # (new in 1.12)
   Enabled: true
 Style/SwapValues: # (new in 1.1)
   Enabled: true
+Style/YAMLFileRead: # new in 1.53
+  Enabled: true
 
 # At the moment not ready to be used
 # https://github.com/bbatsov/rubocop/issues/947

data/CHANGELOG.md

@@ -1,3 +1,37 @@
+## 0.14.4
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Update Javascript: jQuery 3.7.1, KaTeX 0.16.8  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Support Swift `package` access control level.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Initial support for Swift macro declarations.  Requires
+  `--swift-build-tool symbolgraph`.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Support Swift `@_documentation(visibility:)` attribute.  Requires
+  `--swift-build-tool spm|xcodebuild`.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+##### Bug Fixes
+
+* Issue a warning instead of crashing on declarations without names.  
+  [#1325](https://github.com/realm/jazzy/issues/1325)
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Fix extension ordering in symbolgraph mode.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Fix symbolgraph mode crash involving tuple generic constraints.  
+  [John Fairhurst](https://github.com/johnfairh)
+
 ## 0.14.3
 
 ##### Breaking

data/Gemfile

@@ -16,7 +16,7 @@ group :development do
   gem 'webmock'
 
   # Integration tests
-  gem 'clintegracon', '0.7.0'
+  gem 'clintegracon', git: 'https://github.com/mrackwitz/CLIntegracon.git'
   gem 'diffy'
 
   # Code Review

data/Gemfile.lock

@@ -1,13 +1,21 @@
+GIT
+  remote: https://github.com/mrackwitz/CLIntegracon.git
+  revision: ca88b7b8920b6b6542f9b4ad2b1748855783dbae
+  specs:
+    clintegracon (0.9.0)
+      colored2 (~> 3.1)
+      diffy
+
 PATH
   remote: .
   specs:
-    jazzy (0.14.3)
+    jazzy (0.14.4)
       cocoapods (~> 1.5)
       mustache (~> 1.1)
       open4 (~> 1.3)
       redcarpet (~> 3.4)
       rexml (~> 3.2)
-      rouge (>= 2.0.6, < 4.0)
+      rouge (>= 2.0.6, < 5.0)
       sassc (~> 2.1)
       sqlite3 (~> 1.3)
       xcinvoke (~> 0.3.0)
@@ -15,15 +23,14 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (3.0.5)
+    CFPropertyList (3.0.6)
       rexml
-    activesupport (6.1.7)
+    activesupport (7.0.8)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
-      zeitwerk (~> 2.3)
-    addressable (2.8.1)
+    addressable (2.8.5)
       public_suffix (>= 2.0.2, < 6.0)
     algoliasearch (1.27.5)
       httpclient (~> 2.8, >= 2.8.3)
@@ -31,23 +38,21 @@ GEM
     ast (2.4.2)
     atomos (0.1.3)
     bacon (1.2.0)
+    base64 (0.1.1)
     claide (1.1.0)
     claide-plugins (0.9.2)
       cork
       nap
       open4 (~> 1.3)
-    clintegracon (0.7.0)
-      colored (~> 1.2)
-      diffy
-    cocoapods (1.11.3)
+    cocoapods (1.12.1)
       addressable (~> 2.8)
       claide (>= 1.0.2, < 2.0)
-      cocoapods-core (= 1.11.3)
+      cocoapods-core (= 1.12.1)
       cocoapods-deintegrate (>= 1.0.3, < 2.0)
-      cocoapods-downloader (>= 1.4.0, < 2.0)
+      cocoapods-downloader (>= 1.6.0, < 2.0)
       cocoapods-plugins (>= 1.0.0, < 2.0)
       cocoapods-search (>= 1.0.0, < 2.0)
-      cocoapods-trunk (>= 1.4.0, < 2.0)
+      cocoapods-trunk (>= 1.6.0, < 2.0)
       cocoapods-try (>= 1.1.0, < 2.0)
       colored2 (~> 3.1)
       escape (~> 0.0.4)
@@ -55,10 +60,10 @@ GEM
       gh_inspector (~> 1.0)
       molinillo (~> 0.8.0)
       nap (~> 1.0)
-      ruby-macho (>= 1.0, < 3.0)
+      ruby-macho (>= 2.3.0, < 3.0)
       xcodeproj (>= 1.21.0, < 2.0)
-    cocoapods-core (1.11.3)
-      activesupport (>= 5.0, < 7)
+    cocoapods-core (1.12.1)
+      activesupport (>= 5.0, < 8)
       addressable (~> 2.8)
       algoliasearch (~> 1.0)
       concurrent-ruby (~> 1.1)
@@ -76,131 +81,117 @@ GEM
       nap (>= 0.8, < 2.0)
       netrc (~> 0.11)
     cocoapods-try (1.2.0)
-    colored (1.2)
     colored2 (3.1.2)
-    concurrent-ruby (1.1.10)
+    concurrent-ruby (1.2.2)
     cork (0.3.0)
       colored2 (~> 3.1)
     crack (0.4.5)
       rexml
-    danger (8.6.1)
+    danger (9.3.1)
       claide (~> 1.0)
       claide-plugins (>= 0.9.2)
       colored2 (~> 3.1)
       cork (~> 0.1)
-      faraday (>= 0.9.0, < 2.0)
+      faraday (>= 0.9.0, < 3.0)
       faraday-http-cache (~> 2.0)
-      git (~> 1.7)
+      git (~> 1.13)
       kramdown (~> 2.3)
       kramdown-parser-gfm (~> 1.0)
       no_proxy_fix
-      octokit (~> 4.7)
+      octokit (~> 6.0)
       terminal-table (>= 1, < 4)
     diffy (3.4.2)
     escape (0.0.4)
-    ethon (0.15.0)
+    ethon (0.16.0)
       ffi (>= 1.15.0)
-    faraday (1.10.2)
-      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.0)
-      faraday-patron (~> 1.0)
-      faraday-rack (~> 1.0)
-      faraday-retry (~> 1.0)
+    faraday (2.7.11)
+      base64
+      faraday-net_http (>= 2.0, < 3.1)
       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.4.1)
+    faraday-http-cache (2.5.0)
       faraday (>= 0.8)
-    faraday-httpclient (1.0.1)
-    faraday-multipart (1.0.4)
-      multipart-post (~> 2)
-    faraday-net_http (1.0.1)
-    faraday-net_http_persistent (1.2.0)
-    faraday-patron (1.0.0)
-    faraday-rack (1.0.0)
-    faraday-retry (1.0.3)
+    faraday-net_http (3.0.2)
     ffi (1.15.5)
     fourflusher (2.3.1)
     fuzzy_match (2.0.4)
     gh_inspector (1.1.3)
-    git (1.12.0)
+    git (1.18.0)
       addressable (~> 2.8)
       rchardet (~> 1.8)
     hashdiff (1.0.1)
     httpclient (2.8.3)
-    i18n (1.12.0)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
-    json (2.6.2)
+    json (2.6.3)
     kramdown (2.4.0)
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
+    language_server-protocol (3.17.0.3)
     liferaft (0.0.6)
-    mini_portile2 (2.8.0)
-    minitest (5.16.3)
-    mocha (1.14.0)
+    mini_portile2 (2.8.4)
+    minitest (5.20.0)
+    mocha (2.1.0)
+      ruby2_keywords (>= 0.0.5)
     mocha-on-bacon (0.2.3)
       mocha (>= 0.13.0)
     molinillo (0.8.0)
-    multipart-post (2.2.3)
     mustache (1.1.1)
     nanaimo (0.3.0)
     nap (1.1.0)
     netrc (0.11.0)
     no_proxy_fix (0.1.2)
-    octokit (4.25.1)
+    octokit (6.1.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
     open4 (1.3.4)
-    parallel (1.22.1)
-    parser (3.1.2.1)
+    parallel (1.23.0)
+    parser (3.2.2.3)
       ast (~> 2.4.1)
+      racc
     prettybacon (0.0.2)
       bacon (~> 1.2)
     public_suffix (4.0.7)
+    racc (1.7.1)
     rainbow (3.1.1)
     rake (13.0.6)
     rchardet (1.8.0)
-    redcarpet (3.5.1)
-    regexp_parser (2.5.0)
-    rexml (3.2.5)
-    rouge (3.30.0)
-    rubocop (1.36.0)
+    redcarpet (3.6.0)
+    regexp_parser (2.8.1)
+    rexml (3.2.6)
+    rouge (4.1.3)
+    rubocop (1.56.3)
+      base64 (~> 0.1.1)
       json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.1.2.1)
+      parser (>= 3.2.2.3)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.20.1, < 2.0)
+      rubocop-ast (>= 1.28.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.21.0)
-      parser (>= 3.1.1.0)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.29.0)
+      parser (>= 3.2.1.0)
     ruby-macho (2.5.1)
-    ruby-progressbar (1.11.0)
+    ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
     sassc (2.4.0)
       ffi (~> 1.9)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
-    sqlite3 (1.5.0)
+    sqlite3 (1.6.6)
       mini_portile2 (~> 2.8.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
     typhoeus (1.4.0)
       ethon (>= 0.9.0)
-    tzinfo (2.0.5)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.2.0)
-    webmock (3.18.1)
+    unicode-display_width (2.4.2)
+    webmock (3.19.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
@@ -213,7 +204,6 @@ GEM
       colored2 (~> 3.1)
       nanaimo (~> 0.3.0)
       rexml (~> 3.2.4)
-    zeitwerk (2.6.0)
 
 PLATFORMS
   ruby
@@ -221,7 +211,7 @@ PLATFORMS
 DEPENDENCIES
   bacon
   bundler (~> 2.1)
-  clintegracon (= 0.7.0)
+  clintegracon!
   danger
   diffy
   jazzy!
@@ -233,4 +223,4 @@ DEPENDENCIES
   webmock
 
 BUNDLED WITH
-   2.2.22
+   2.3.26

data/README.md

@@ -214,16 +214,14 @@ sourcekitten doc --objc $(pwd)/MyProject/MyProject.h \
       -I $(pwd) -fmodules > objcDoc.json
 
 # Feed both outputs to Jazzy as a comma-separated list
-jazzy --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
+jazzy --module MyProject --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
 ```
 
 ### Docs from `.swiftmodule`s or frameworks
 
-*This feature is new and relies on a new Swift feature: there may be crashes
-and mistakes: reports welcome.*
+*This feature is new: there may be crashes and mistakes. Reports welcome.*
 
-Swift 5.3 adds support for symbol graph generation from `.swiftmodule` files.
-This looks to be part of Apple's toolchain for generating their online docs.
+Swift 5.3 added support for symbol graph generation from `.swiftmodule` files.
 
 Jazzy can use this to generate API documentation.  This is faster than using
 the source code directly but does have limitations: for example documentation
@@ -360,25 +358,69 @@ Note that the `--include` option is applied before the `--exclude` option. For e
 Declarations with a documentation comment containing `:nodoc:` are excluded from the
 documentation.
 
+Declarations with the `@_documentation(visibility:)` attribute are treated as though they
+are written with the given visibility.  You can use this as a replacement for `:nodoc:` as
+part of a transition to Apple's DocC but it is not compatible with Jazzy's symbolgraph mode.
+
 ### Documentation structure
 
-By default Jazzy does not create separate web pages for declarations that do
-not have any members: instead they are nested into some parent page.  Use the
-`--separate-global-declarations` flag to change this and always create pages
-for declarations that can be directly accessed from client code.
+Jazzy arranges documentation into categories.  The default categories are things
+like _Classes_ and _Structures_ corresponding to programming-language concepts,
+as well as _Guides_ if `--documentation` is set.
+
+You can customize the categories and their contents using `custom_categories` in
+the config file — see the ReSwift [docs](https://reswift.github.io/ReSwift/) and
+[config file](https://github.com/ReSwift/ReSwift/blob/e94737282850fa038b625b4e351d1608a3d02cee/.jazzy.json)
+for an example.
+
+Within each category the items are ordered first alphabetically by source
+filename, and then by declaration order within the file.  You can use
+`// MARK:` comments within the file to create subheadings on the page, for
+example to split up properties and methods.  There’s no way to customize this
+order short of editing either the generated web page or the SourceKitten JSON.
+
+Swift extensions and Objective-C categories allow type members to be declared
+across multiple source files.  In general, extensions follow the main type
+declaration: first extensions from the same source file, then extensions from
+other files ordered alphabetically by filename.  Swift conditional extensions
+(`extension A where …`) always appear beneath unconditional extensions.
+
+Use this pattern to add or customize the subheading before extension members:
+```swift
+extension MyType {
+  // MARK: Subheading for this group of methods
+  …
+}
+```
+
+When Jazzy is using `--swift-build-tool symgraph` the source file names and
+line numbers may not be available. In this case the ordering is approximately
+alphabetical by symbol name and USR; the order is stable for the same input.
+
+Jazzy does not normally create separate web pages for declarations that do not
+have any members -- instead they are entirely nested into their parent page.  Use
+the `--separate-global-declarations` flag to change this and  create pages for
+these empty types.
 
 ### Choosing the Swift language version
 
 Jazzy normally uses the Swift compiler from the Xcode currently configured by
-`xcode-select`.  Use the `--swift-version` flag to compile with a different
-Xcode.
+`xcode-select`.  Use the `--swift-version` flag or the `DEVELOPER_DIR` environment
+variable to compile with a different Xcode.
 
 The value you pass to `--swift-version` must be the Swift language version given
-by `swift --version` in the Xcode you want to use.
+by `swift --version` in the Xcode you want to use. Jazzy uses
+[xcinvoke](https://github.com/segiddins/xcinvoke) to find a suitable Xcode
+installation on your system. This can be slow: if you know where Xcode is
+installed then it's faster to set `DEVELOPER_DIR` directly.
 
-For example to use Xcode 9.4:
+For example to use Xcode 14:
 ```shell
-jazzy --swift-version 4.1.2
+jazzy --swift-version 5.7
+```
+...or:
+```shell
+DEVELOPER_DIR=/Applications/Xcode_14.app/Contents/Developer jazzy
 ```
 
 ## Linux
@@ -423,6 +465,36 @@ Check the `--min-acl` setting -- see [above](#controlling-what-is-documented).
 
 See [this document](ObjectiveC.md).
 
+### Miscellaneous
+
+**Missing docset**
+
+Jazzy only builds a docset when you set the `--module` flag.
+
+**Unable to pass --build-tool-arguments containing commas**
+
+If you want Jazzy to run something like `xcodebuild -scheme Scheme -destination 'a=x,b=y,c=z'`
+then you must use the config file instead of the CLI flag because the CLI parser
+that Jazzy uses cannot handle arguments that themselves contain commas.
+
+The example config file here would be:
+```yaml
+build_tool_arguments:
+  - "-scheme"
+  - "Scheme"
+  - "-destination"
+  - "a=x,b=y,c=z"
+```
+
+**Errors running in an Xcode Run Script phase**
+
+Running Jazzy from an Xcode build phase can go wrong in cryptic ways when Jazzy
+has to run `xcodebuild`.
+
+Users [have reported](https://github.com/realm/jazzy/issues/1012) that error
+messages about symbols lacking USRs can be fixed by unsetting
+`LLVM_TARGET_TRIPLE_SUFFIX` as part of the run script.
+
 ### Installation Problems
 
 **Can't find header files / clang**

data/Rakefile

@@ -71,7 +71,7 @@ begin
       destination = "spec/integration_specs/#{source.gsub('tmp/', '')}/after"
       if File.exist?(destination)
         sh "rm -rf #{destination}"
-        sh "mv #{source} #{destination}"
+        sh "mv #{source}/transformed #{destination}"
       end
     end