jazzy 0.14.1 → 0.14.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/Tests.yml +4 -4
- data/.rubocop.yml +17 -1
- data/CHANGELOG.md +28 -0
- data/CONTRIBUTING.md +1 -1
- data/Gemfile.lock +33 -29
- data/ObjectiveC.md +208 -0
- data/README.md +39 -24
- data/Rakefile +5 -3
- data/bin/sourcekitten +0 -0
- data/jazzy.gemspec +2 -1
- data/lib/jazzy/config.rb +13 -0
- data/lib/jazzy/gem_version.rb +1 -1
- data/lib/jazzy/highlighter.rb +0 -12
- data/lib/jazzy/search_builder.rb +3 -5
- data/lib/jazzy/source_declaration.rb +4 -2
- data/lib/jazzy/sourcekitten.rb +3 -1
- data/lib/jazzy/symbol_graph.rb +28 -17
- data/spec/integration_spec.rb +2 -3
- metadata +7 -5
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: e5d4f36fe547b9d232250c291bde5c20c12132335609b7de4e7cb39af6e2586c
|
4
|
+
data.tar.gz: 2c310fd944aa0cdd6565f6af00bf303526d392ed6d41626da2eb89c95222330b
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 2994093e3bfcf803a5479b9d9fe2132f0b26027d11d0ca44754aa0a6b8af1ebbdd1fd0838efa42bacc921ac81286c041294195f1c2d39b092162deccce0d5ab1
|
7
|
+
data.tar.gz: 98a0573749bbd37464e910b9d22fe98d0dfd3804f26f313b1d9b743d39c4dd023fbbb793316ce08a20168f18c5b8242a3f4b5216bdbcaeffbda27615cb67b699
|
data/.github/workflows/Tests.yml
CHANGED
@@ -15,14 +15,14 @@ jobs:
|
|
15
15
|
with:
|
16
16
|
ruby-version: 2.6
|
17
17
|
bundler-cache: true
|
18
|
+
- name: Rubocop
|
19
|
+
run: |
|
20
|
+
bundle exec rake rubocop
|
18
21
|
- name: Danger
|
19
22
|
env:
|
20
23
|
DANGER_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
21
24
|
run: |
|
22
25
|
bundle exec danger --verbose
|
23
|
-
- name: Rubocop
|
24
|
-
run: |
|
25
|
-
bundle exec rake rubocop
|
26
26
|
|
27
27
|
spec:
|
28
28
|
runs-on: macos-11
|
@@ -31,7 +31,7 @@ jobs:
|
|
31
31
|
matrix:
|
32
32
|
spec: ["objc_spec", "swift_spec", "cocoapods_spec"]
|
33
33
|
env:
|
34
|
-
DEVELOPER_DIR: /Applications/Xcode_13.
|
34
|
+
DEVELOPER_DIR: /Applications/Xcode_13.2.app/Contents/Developer
|
35
35
|
steps:
|
36
36
|
- uses: actions/checkout@v2
|
37
37
|
with:
|
data/.rubocop.yml
CHANGED
@@ -7,10 +7,12 @@ AllCops:
|
|
7
7
|
SuggestExtensions: false
|
8
8
|
TargetRubyVersion: 2.6
|
9
9
|
|
10
|
-
#- Pending Cops as of 1.
|
10
|
+
#- Pending Cops as of 1.26.0 ---------------------------------------------#
|
11
11
|
|
12
12
|
Gemspec/DateAssignment: # (new in 1.10)
|
13
13
|
Enabled: true
|
14
|
+
Gemspec/RequireMFA: # new in 1.23
|
15
|
+
Enabled: true
|
14
16
|
Layout/SpaceBeforeBrackets: # (new in 1.7)
|
15
17
|
Enabled: true
|
16
18
|
Lint/AmbiguousAssignment: # (new in 1.7)
|
@@ -53,6 +55,10 @@ Lint/UnexpectedBlockArity: # (new in 1.5)
|
|
53
55
|
Enabled: true
|
54
56
|
Lint/UnmodifiedReduceAccumulator: # (new in 1.1)
|
55
57
|
Enabled: true
|
58
|
+
Lint/UselessRuby2Keywords: # new in 1.23
|
59
|
+
Enabled: true
|
60
|
+
Naming/BlockForwarding: # new in 1.24
|
61
|
+
Enabled: true
|
56
62
|
Naming/InclusiveLanguage: # (new in 1.18)
|
57
63
|
Enabled: true
|
58
64
|
Security/IoMethods: # new in 1.22
|
@@ -65,6 +71,10 @@ Style/DocumentDynamicEvalDefinition: # (new in 1.1)
|
|
65
71
|
Enabled: true
|
66
72
|
Style/EndlessMethod: # (new in 1.8)
|
67
73
|
Enabled: true
|
74
|
+
Style/FileRead: # new in 1.24
|
75
|
+
Enabled: true
|
76
|
+
Style/FileWrite: # new in 1.24
|
77
|
+
Enabled: true
|
68
78
|
Style/HashConversion: # (new in 1.10)
|
69
79
|
Enabled: true
|
70
80
|
Style/HashExcept: # (new in 1.7)
|
@@ -73,16 +83,22 @@ Style/IfWithBooleanLiteralBranches: # (new in 1.9)
|
|
73
83
|
Enabled: true
|
74
84
|
Style/InPatternThen: # (new in 1.16)
|
75
85
|
Enabled: true
|
86
|
+
Style/MapToHash: # new in 1.24
|
87
|
+
Enabled: true
|
76
88
|
Style/MultilineInPatternThen: # (new in 1.16)
|
77
89
|
Enabled: true
|
78
90
|
Style/NegatedIfElseCondition: # (new in 1.2)
|
79
91
|
Enabled: true
|
92
|
+
Style/NestedFileDirname: # new in 1.26
|
93
|
+
Enabled: true
|
80
94
|
Style/NilLambda: # (new in 1.3)
|
81
95
|
Enabled: true
|
82
96
|
Style/NumberedParameters: # new in 1.22
|
83
97
|
Enabled: true
|
84
98
|
Style/NumberedParametersLimit: # new in 1.22
|
85
99
|
Enabled: true
|
100
|
+
Style/OpenStructUse: # new in 1.23
|
101
|
+
Enabled: true
|
86
102
|
Style/QuotedSymbols: # (new in 1.16)
|
87
103
|
Enabled: true
|
88
104
|
Style/RedundantArgument: # (new in 1.4)
|
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,31 @@
|
|
1
|
+
## 0.14.2
|
2
|
+
|
3
|
+
##### Breaking
|
4
|
+
|
5
|
+
* When building with Swift 5.6 and not passing `—-module` to Jazzy, declarations
|
6
|
+
may not be correctly identified as undocumented and docs may include unwanted
|
7
|
+
extensions. Pass `—-module MyModuleName` to fix this.
|
8
|
+
[John Fairhurst](https://github.com/johnfairh)
|
9
|
+
|
10
|
+
##### Enhancements
|
11
|
+
|
12
|
+
* Support using pre-generated symbolgraph files in Swift symbolgraph mode.
|
13
|
+
[Nathan Wong](https://github.com/esteluk)
|
14
|
+
|
15
|
+
* Issue a warning on some combinations of Objective-C flags.
|
16
|
+
[John Fairhurst](https://github.com/johnfairh)
|
17
|
+
[#900](https://github.com/realm/jazzy/issues/900)
|
18
|
+
|
19
|
+
* Support Swift 5.6. The bundled `sourcekitten` is a universal binary.
|
20
|
+
[John Fairhurst](https://github.com/johnfairh)
|
21
|
+
|
22
|
+
##### Bug Fixes
|
23
|
+
|
24
|
+
* In Swift symbolgraph mode, stop including extensions to types that are beneath
|
25
|
+
the minimum ACL.
|
26
|
+
[John Fairhurst](https://github.com/johnfairh)
|
27
|
+
[#1291](https://github.com/realm/jazzy/issues/1291)
|
28
|
+
|
1
29
|
## 0.14.1
|
2
30
|
|
3
31
|
##### Breaking
|
data/CONTRIBUTING.md
CHANGED
@@ -49,7 +49,7 @@ git push
|
|
49
49
|
You'll need push access to the integration specs repo to do this. You can
|
50
50
|
request access from one of the maintainers when filing your PR.
|
51
51
|
|
52
|
-
You must have Xcode 13 installed to build the integration specs.
|
52
|
+
You must have Xcode 13.2 installed to build the integration specs.
|
53
53
|
|
54
54
|
## Making changes to SourceKitten
|
55
55
|
|
data/Gemfile.lock
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
PATH
|
2
2
|
remote: .
|
3
3
|
specs:
|
4
|
-
jazzy (0.14.
|
4
|
+
jazzy (0.14.2)
|
5
5
|
cocoapods (~> 1.5)
|
6
6
|
mustache (~> 1.1)
|
7
7
|
open4 (~> 1.3)
|
@@ -15,9 +15,9 @@ PATH
|
|
15
15
|
GEM
|
16
16
|
remote: https://rubygems.org/
|
17
17
|
specs:
|
18
|
-
CFPropertyList (3.0.
|
18
|
+
CFPropertyList (3.0.5)
|
19
19
|
rexml
|
20
|
-
activesupport (6.1.
|
20
|
+
activesupport (6.1.5)
|
21
21
|
concurrent-ruby (~> 1.0, >= 1.0.2)
|
22
22
|
i18n (>= 1.6, < 2)
|
23
23
|
minitest (>= 5.1)
|
@@ -31,7 +31,7 @@ GEM
|
|
31
31
|
ast (2.4.2)
|
32
32
|
atomos (0.1.3)
|
33
33
|
bacon (1.2.0)
|
34
|
-
claide (1.0
|
34
|
+
claide (1.1.0)
|
35
35
|
claide-plugins (0.9.2)
|
36
36
|
cork
|
37
37
|
nap
|
@@ -39,10 +39,10 @@ GEM
|
|
39
39
|
clintegracon (0.7.0)
|
40
40
|
colored (~> 1.2)
|
41
41
|
diffy
|
42
|
-
cocoapods (1.11.
|
42
|
+
cocoapods (1.11.3)
|
43
43
|
addressable (~> 2.8)
|
44
44
|
claide (>= 1.0.2, < 2.0)
|
45
|
-
cocoapods-core (= 1.11.
|
45
|
+
cocoapods-core (= 1.11.3)
|
46
46
|
cocoapods-deintegrate (>= 1.0.3, < 2.0)
|
47
47
|
cocoapods-downloader (>= 1.4.0, < 2.0)
|
48
48
|
cocoapods-plugins (>= 1.0.0, < 2.0)
|
@@ -57,7 +57,7 @@ GEM
|
|
57
57
|
nap (~> 1.0)
|
58
58
|
ruby-macho (>= 1.0, < 3.0)
|
59
59
|
xcodeproj (>= 1.21.0, < 2.0)
|
60
|
-
cocoapods-core (1.11.
|
60
|
+
cocoapods-core (1.11.3)
|
61
61
|
activesupport (>= 5.0, < 7)
|
62
62
|
addressable (~> 2.8)
|
63
63
|
algoliasearch (~> 1.0)
|
@@ -83,7 +83,7 @@ GEM
|
|
83
83
|
colored2 (~> 3.1)
|
84
84
|
crack (0.4.5)
|
85
85
|
rexml
|
86
|
-
danger (8.4.
|
86
|
+
danger (8.4.5)
|
87
87
|
claide (~> 1.0)
|
88
88
|
claide-plugins (>= 0.9.2)
|
89
89
|
colored2 (~> 3.1)
|
@@ -98,18 +98,19 @@ GEM
|
|
98
98
|
terminal-table (>= 1, < 4)
|
99
99
|
diffy (3.4.0)
|
100
100
|
escape (0.0.4)
|
101
|
-
ethon (0.
|
101
|
+
ethon (0.15.0)
|
102
102
|
ffi (>= 1.15.0)
|
103
|
-
faraday (1.
|
103
|
+
faraday (1.10.0)
|
104
104
|
faraday-em_http (~> 1.0)
|
105
105
|
faraday-em_synchrony (~> 1.0)
|
106
106
|
faraday-excon (~> 1.1)
|
107
|
-
faraday-httpclient (~> 1.0
|
107
|
+
faraday-httpclient (~> 1.0)
|
108
|
+
faraday-multipart (~> 1.0)
|
108
109
|
faraday-net_http (~> 1.0)
|
109
|
-
faraday-net_http_persistent (~> 1.
|
110
|
+
faraday-net_http_persistent (~> 1.0)
|
110
111
|
faraday-patron (~> 1.0)
|
111
112
|
faraday-rack (~> 1.0)
|
112
|
-
|
113
|
+
faraday-retry (~> 1.0)
|
113
114
|
ruby2_keywords (>= 0.0.4)
|
114
115
|
faraday-em_http (1.0.0)
|
115
116
|
faraday-em_synchrony (1.0.0)
|
@@ -117,27 +118,30 @@ GEM
|
|
117
118
|
faraday-http-cache (2.2.0)
|
118
119
|
faraday (>= 0.8)
|
119
120
|
faraday-httpclient (1.0.1)
|
121
|
+
faraday-multipart (1.0.3)
|
122
|
+
multipart-post (>= 1.2, < 3)
|
120
123
|
faraday-net_http (1.0.1)
|
121
124
|
faraday-net_http_persistent (1.2.0)
|
122
125
|
faraday-patron (1.0.0)
|
123
126
|
faraday-rack (1.0.0)
|
124
|
-
|
127
|
+
faraday-retry (1.0.3)
|
128
|
+
ffi (1.15.5)
|
125
129
|
fourflusher (2.3.1)
|
126
130
|
fuzzy_match (2.0.4)
|
127
131
|
gh_inspector (1.1.3)
|
128
|
-
git (1.
|
132
|
+
git (1.10.2)
|
129
133
|
rchardet (~> 1.8)
|
130
134
|
hashdiff (1.0.1)
|
131
135
|
httpclient (2.8.3)
|
132
|
-
i18n (1.
|
136
|
+
i18n (1.10.0)
|
133
137
|
concurrent-ruby (~> 1.0)
|
134
|
-
json (2.
|
138
|
+
json (2.6.1)
|
135
139
|
kramdown (2.3.1)
|
136
140
|
rexml
|
137
141
|
kramdown-parser-gfm (1.1.0)
|
138
142
|
kramdown (~> 2.0)
|
139
143
|
liferaft (0.0.6)
|
140
|
-
minitest (5.
|
144
|
+
minitest (5.15.0)
|
141
145
|
mocha (1.13.0)
|
142
146
|
mocha-on-bacon (0.2.3)
|
143
147
|
mocha (>= 0.13.0)
|
@@ -148,34 +152,34 @@ GEM
|
|
148
152
|
nap (1.1.0)
|
149
153
|
netrc (0.11.0)
|
150
154
|
no_proxy_fix (0.1.2)
|
151
|
-
octokit (4.
|
155
|
+
octokit (4.22.0)
|
152
156
|
faraday (>= 0.9)
|
153
157
|
sawyer (~> 0.8.0, >= 0.5.3)
|
154
158
|
open4 (1.3.4)
|
155
159
|
parallel (1.21.0)
|
156
|
-
parser (3.
|
160
|
+
parser (3.1.1.0)
|
157
161
|
ast (~> 2.4.1)
|
158
162
|
prettybacon (0.0.2)
|
159
163
|
bacon (~> 1.2)
|
160
164
|
public_suffix (4.0.6)
|
161
|
-
rainbow (3.
|
165
|
+
rainbow (3.1.1)
|
162
166
|
rake (13.0.6)
|
163
167
|
rchardet (1.8.0)
|
164
168
|
redcarpet (3.5.1)
|
165
|
-
regexp_parser (2.
|
169
|
+
regexp_parser (2.2.1)
|
166
170
|
rexml (3.2.5)
|
167
|
-
rouge (3.
|
168
|
-
rubocop (1.
|
171
|
+
rouge (3.28.0)
|
172
|
+
rubocop (1.26.0)
|
169
173
|
parallel (~> 1.10)
|
170
|
-
parser (>= 3.
|
174
|
+
parser (>= 3.1.0.0)
|
171
175
|
rainbow (>= 2.2.2, < 4.0)
|
172
176
|
regexp_parser (>= 1.8, < 3.0)
|
173
177
|
rexml
|
174
|
-
rubocop-ast (>= 1.
|
178
|
+
rubocop-ast (>= 1.16.0, < 2.0)
|
175
179
|
ruby-progressbar (~> 1.7)
|
176
180
|
unicode-display_width (>= 1.4.0, < 3.0)
|
177
|
-
rubocop-ast (1.
|
178
|
-
parser (>= 3.
|
181
|
+
rubocop-ast (1.16.0)
|
182
|
+
parser (>= 3.1.1.0)
|
179
183
|
ruby-macho (2.5.1)
|
180
184
|
ruby-progressbar (1.11.0)
|
181
185
|
ruby2_keywords (0.0.5)
|
@@ -205,7 +209,7 @@ GEM
|
|
205
209
|
colored2 (~> 3.1)
|
206
210
|
nanaimo (~> 0.3.0)
|
207
211
|
rexml (~> 3.2.4)
|
208
|
-
zeitwerk (2.4
|
212
|
+
zeitwerk (2.5.4)
|
209
213
|
|
210
214
|
PLATFORMS
|
211
215
|
ruby
|
data/ObjectiveC.md
ADDED
@@ -0,0 +1,208 @@
|
|
1
|
+
This document is about Jazzy's Objective-C documentation generation.
|
2
|
+
|
3
|
+
It's intended for users who are having problems after trying to follow the
|
4
|
+
examples in the [README](README.md#objective-c). It gives some solutions to
|
5
|
+
common problems and explains how the system works to help users work through
|
6
|
+
uncommon problems.
|
7
|
+
|
8
|
+
* [How it works](#how-objective-c-docs-generation-works)
|
9
|
+
* Common problems:
|
10
|
+
* [Apple SDK include failure](#problem-apple-sdk-importinclude-failure)
|
11
|
+
* [Non-SDK include failure](#problem-non-sdk-include-failure)
|
12
|
+
* [Argument list too long](#problem-argument-list-too-long-e2big-and-more)
|
13
|
+
* [Enum cases with wrong doc comment](#problem-enum-cases-have-the-wrong-doc-comment)
|
14
|
+
* [Swift API versions missing](#problem-swift-api-versions-are-all-missing)
|
15
|
+
* [Swift API versions use `Any`](#problem-swift-api-versions-have-any-instead-of-type-name)
|
16
|
+
* [Structural `NS_SWIFT_NAME` not working](#problem-structural-ns_swift_name-not-working)
|
17
|
+
|
18
|
+
# How Objective-C docs generation works
|
19
|
+
|
20
|
+
Jazzy uses `libclang` to generate docs for Objective-C projects. You can think
|
21
|
+
of this as running some parts of the `clang` compiler against a header file.
|
22
|
+
Jazzy refers to this header file as the _umbrella header_ but it does not have
|
23
|
+
to be the umbrella header from a Clang module: it's just the header file that
|
24
|
+
includes everything to be documented.
|
25
|
+
|
26
|
+
This means there are two problems to solve:
|
27
|
+
1. What `clang` flags are required; and
|
28
|
+
2. How to pass them to the tools.
|
29
|
+
|
30
|
+
Jazzy has two modes here: a smart mode that covers 90% of projects and a direct mode where the user provides all the flags.
|
31
|
+
|
32
|
+
> *Important*: Jazzy does _not_ use any Objective-C build settings from your
|
33
|
+
Xcode project or `Package.swift`. If your project needs special settings
|
34
|
+
such as `#define`s then you need to repeat those in the Jazzy invocation.
|
35
|
+
|
36
|
+
## Direct mode
|
37
|
+
|
38
|
+
Passing a basic set of `clang` flags looks like this:
|
39
|
+
|
40
|
+
```shell
|
41
|
+
jazzy ...
|
42
|
+
--objc
|
43
|
+
--build-tool-arguments
|
44
|
+
--objc,MyProject/MyProject.h,--,-x,objective-c,
|
45
|
+
-isysroot,$(xcrun --show-sdk-path),
|
46
|
+
-I,$(pwd),
|
47
|
+
-fmodules
|
48
|
+
```
|
49
|
+
The `--build-tool-arguments` are arguments to `sourcekitten`. Everything after
|
50
|
+
the `--` are the `clang` flags that will be used with the header file given
|
51
|
+
before the `--`.
|
52
|
+
|
53
|
+
You can try these flags outside of Jazzy's environment:
|
54
|
+
```shell
|
55
|
+
clang -c -x objective-c -isysroot $(xcrun --show-sdk-path) -I $(pwd) MyProject/MyProject.h -fmodules
|
56
|
+
```
|
57
|
+
(The `-c` stops `clang` from trying to link an executable.)
|
58
|
+
|
59
|
+
This is a good method of experimenting with compiler flags to get a working
|
60
|
+
build without getting bogged down in the Jazzy and SourceKitten layers.
|
61
|
+
|
62
|
+
## Smart mode
|
63
|
+
|
64
|
+
The smart mode takes the variable parts of the basic set of flags and maps
|
65
|
+
them from Jazzy flags:
|
66
|
+
```shell
|
67
|
+
jazzy ...
|
68
|
+
--objc
|
69
|
+
--umbrella-header MyProject/MyProject.h
|
70
|
+
--framework-root $(pwd)
|
71
|
+
[--sdk <sdk name>]
|
72
|
+
```
|
73
|
+
|
74
|
+
The `--umbrella-header` maps directly to the file passed to `sourcekitten`.
|
75
|
+
|
76
|
+
The `--framework-root` is used for the `-I` include path, as well as every
|
77
|
+
directory beneath it, recursively. So if your project structure looks like:
|
78
|
+
```
|
79
|
+
MyProject/
|
80
|
+
Sources/
|
81
|
+
Main/
|
82
|
+
Extension/
|
83
|
+
```
|
84
|
+
... and you pass `--framework-root MyProject`, then the `-I` flags passed to
|
85
|
+
`clang` are `-I MyProject -I MyProject/Sources -I MyProject/Sources/Main -I
|
86
|
+
MyProject/Sources/Extension`. This feature helps some projects resolve
|
87
|
+
`#include` directives.
|
88
|
+
|
89
|
+
Finally the `--sdk` option is passed through instead of the default `macosx` to
|
90
|
+
find the SDK.
|
91
|
+
|
92
|
+
## Mixing modes
|
93
|
+
|
94
|
+
Do not mix modes. For example do not set both `--umbrella-header` and
|
95
|
+
`--build-tool-arguments`. Jazzy does not flag this as an error for
|
96
|
+
historical compatibility reasons, but the results are at best confusing.
|
97
|
+
|
98
|
+
# Problem: Apple SDK import/include failure
|
99
|
+
|
100
|
+
For example `fatal error: module 'UIKit' not found`.
|
101
|
+
|
102
|
+
This means Jazzy is using the wrong SDK: the default is for macOS which does
|
103
|
+
not have `UIKit`. Use `--sdk iphonesimulator`.
|
104
|
+
|
105
|
+
# Problem: Non-SDK include failure
|
106
|
+
|
107
|
+
For example `fatal error: 'MyModule/SomeHeader.h' file not found`.
|
108
|
+
|
109
|
+
This means `clang` is not being passed the right flags to resolve a `#include` /
|
110
|
+
`#import`.
|
111
|
+
|
112
|
+
Start by finding the header file in the filesystem. You might be able to fix
|
113
|
+
the problem just by adding extra `-I <path>` flags.
|
114
|
+
|
115
|
+
Usually though the problem is that Xcode has done something clever that needs
|
116
|
+
to be worked around or replicated.
|
117
|
+
|
118
|
+
Xcode uses technology including Clang header maps to let files be found using
|
119
|
+
lines like `#import <ModuleName/Header.h>` even when there is no such
|
120
|
+
filesystem directory.
|
121
|
+
|
122
|
+
To make the Jazzy build work you need to make these `#include`s work. The
|
123
|
+
solution depends on your project structure. Some suggestions in rough order
|
124
|
+
of complexity:
|
125
|
+
* Use symlinks to create an equivalent directory tree. For example if
|
126
|
+
`Header.h` is inside `Sources/include` then symlink that directory to
|
127
|
+
`ModuleName` and pass `-I $(pwd)`.
|
128
|
+
|
129
|
+
* Copy/link your header files into a throwaway directory tree that matches
|
130
|
+
the required structure and is used just for building docs.
|
131
|
+
|
132
|
+
* Create a 'docs header file' separate to the framework's regular umbrella
|
133
|
+
header that contains only filesystem-correct `#import`s.
|
134
|
+
|
135
|
+
* If you are happy to build the framework project before generating docs and
|
136
|
+
all the problematic paths have the form `ModuleName/PublicHeader.h` then
|
137
|
+
have `clang` resolve those includes to the built framework by passing
|
138
|
+
`-F <path of directory containing ModuleName.framework>`.
|
139
|
+
|
140
|
+
* If you are happy to build the project before generating docs then you may
|
141
|
+
be able to use the header maps Xcode has generated. Check the build log in
|
142
|
+
Xcode to find them and the invocation syntax.
|
143
|
+
|
144
|
+
* Manually construct an equivalent header map. This is complex not least
|
145
|
+
because Apple does not make tools or proper documentation available.
|
146
|
+
[An open-source starting point](https://milen.me/writings/swift-module-maps-vfs-overlays-header-maps/).
|
147
|
+
|
148
|
+
# Problem: Argument list too long `E2BIG` (and more...)
|
149
|
+
|
150
|
+
For example ``...open4.rb:49:in `exec': Argument list too long - [...]/bin/sourcekitten (Errno::E2BIG)``
|
151
|
+
|
152
|
+
Can also manifest as 'generally weird' errors such as `sourcekitten` just
|
153
|
+
crashing and `fatal error: could not build module 'Foundation'`.
|
154
|
+
|
155
|
+
This means `--framework-root` is trying to add too many include directories:
|
156
|
+
there are too many subdirectories of its parameter. If you cannot change this
|
157
|
+
to something more specific that works then you need to use Jazzy's
|
158
|
+
[direct mode](#direct-mode) to pass in the correct directories.
|
159
|
+
|
160
|
+
# Problem: Enum cases have the wrong doc comment
|
161
|
+
|
162
|
+
If you write an enum case with a doc comment followed by an enum case without
|
163
|
+
a doc comment, then both get the same doc comment.
|
164
|
+
|
165
|
+
This seems to be a bug in `libclang`. The only workaround is to add the missing
|
166
|
+
doc comment.
|
167
|
+
|
168
|
+
# Problem: Swift API versions are all missing
|
169
|
+
|
170
|
+
This usually means the `clang` flags are malformed in a way that is ignored by
|
171
|
+
`libclang` but not by the Swift Objective-C importer.
|
172
|
+
|
173
|
+
One easy way to accidentally do this is passing `-I` without a path, for
|
174
|
+
example `--build-tool-flags ...,-I,-I,Headers`,....
|
175
|
+
|
176
|
+
This also sometimes happens if you are frequently switching back and forth
|
177
|
+
between some Swift / Xcode versions -- it's a bug somewhere in the Apple tools.
|
178
|
+
The bad state goes away with time / reboot.
|
179
|
+
|
180
|
+
# Problem: Swift API versions have `Any` instead of type name
|
181
|
+
|
182
|
+
Jazzy finds the Swift version of an Objective-C API using the SourceKit
|
183
|
+
`source.request.editor.open.interface.header` request on the header file that
|
184
|
+
contains the declaration, passing in the same `clang` flags used for the
|
185
|
+
umbrella header. [See the code](https://github.com/jpsim/SourceKitten/blob/bed112c313ca8c3c149f8cb84069f1c080e86a7e/Source/SourceKittenFramework/Clang%2BSourceKitten.swift#L202).
|
186
|
+
|
187
|
+
This means that each header file needs to compile standalone, without
|
188
|
+
any implicit dependencies. For example:
|
189
|
+
```
|
190
|
+
MyModule.h // umbrella, includes MyClass.h then Utils.h
|
191
|
+
MyClass.h // @interface MyClass ... @end
|
192
|
+
Utils.h // void my_function( MyClass * myClass);
|
193
|
+
```
|
194
|
+
Here, `Utils.h` has an implicit dependency on `MyClass.h` that is normally
|
195
|
+
satisfied by the include order of `MyModule.h`. One fix that allows `Utils.h`
|
196
|
+
to compile standalone is to add `@class MyClass;`.
|
197
|
+
|
198
|
+
# Problem: Structural `NS_SWIFT_NAME` not working
|
199
|
+
|
200
|
+
The `NS_SWIFT_NAME` macro is mostly used to give an Objective-C API a
|
201
|
+
different name in Swift. There are no known problems with this part.
|
202
|
+
|
203
|
+
The macro can also be used to change the 'structure' of an API, for example
|
204
|
+
make a C global function appear as a member function in Swift, or make a C
|
205
|
+
class appear as a nested type in Swift.
|
206
|
+
|
207
|
+
Jazzy doesn't understand or communicate these structural changes: you'll need
|
208
|
+
to explain it in doc comments.
|
data/README.md
CHANGED
@@ -67,7 +67,7 @@ Here are some resources with tutorials and examples, starting with the most mode
|
|
67
67
|
* 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).
|
68
68
|
|
69
69
|
For Objective-C documentation the same keywords are supported, but note that the format
|
70
|
-
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 @
|
70
|
+
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.**
|
71
71
|
|
72
72
|
Jazzy can also generate cross-references within your documentation. A symbol name in
|
73
73
|
backticks generates a link, for example:
|
@@ -139,20 +139,36 @@ jazzy \
|
|
139
139
|
|
140
140
|
### Objective-C
|
141
141
|
|
142
|
-
To generate documentation for Objective-C
|
143
|
-
parameters
|
144
|
-
|
142
|
+
To generate documentation for a simple Objective-C project, you must pass the
|
143
|
+
following parameters:
|
145
144
|
* `--objc`
|
146
145
|
* `--umbrella-header ...`
|
147
146
|
* `--framework-root ...`
|
148
|
-
|
147
|
+
|
148
|
+
...and optionally:
|
149
|
+
* `--sdk [iphone|watch|appletv][os|simulator]|macosx` (default value
|
149
150
|
of `macosx`)
|
150
|
-
* `--hide-declarations [objc|swift]` (
|
151
|
-
declarations)
|
151
|
+
* `--hide-declarations [objc|swift]` (hides the selected language declarations)
|
152
152
|
|
153
|
-
|
153
|
+
For example, this is how the `AFNetworking` docs are generated:
|
154
|
+
|
155
|
+
```shell
|
156
|
+
jazzy \
|
157
|
+
--objc \
|
158
|
+
--author AFNetworking \
|
159
|
+
--author_url http://afnetworking.com \
|
160
|
+
--source-host github \
|
161
|
+
--source-host-url https://github.com/AFNetworking/AFNetworking \
|
162
|
+
--source-host-files-url https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
|
163
|
+
--module-version 2.6.2 \
|
164
|
+
--umbrella-header AFNetworking/AFNetworking.h \
|
165
|
+
--framework-root . \
|
166
|
+
--module AFNetworking
|
167
|
+
```
|
154
168
|
|
155
|
-
|
169
|
+
For a more complicated Objective-C project, instead use `--build-tool-arguments`
|
170
|
+
to pass arbitrary compiler flags. For example, this is how Realm Objective-C
|
171
|
+
docs are generated:
|
156
172
|
|
157
173
|
```shell
|
158
174
|
jazzy \
|
@@ -171,21 +187,8 @@ jazzy \
|
|
171
187
|
--head "$(cat docs/custom_head.html)"
|
172
188
|
```
|
173
189
|
|
174
|
-
|
175
|
-
|
176
|
-
```shell
|
177
|
-
jazzy \
|
178
|
-
--objc \
|
179
|
-
--author AFNetworking \
|
180
|
-
--author_url http://afnetworking.com \
|
181
|
-
--source-host github \
|
182
|
-
--source-host-url https://github.com/AFNetworking/AFNetworking \
|
183
|
-
--source-host-files-url https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
|
184
|
-
--module-version 2.6.2 \
|
185
|
-
--umbrella-header AFNetworking/AFNetworking.h \
|
186
|
-
--framework-root . \
|
187
|
-
--module AFNetworking
|
188
|
-
```
|
190
|
+
See [the Objective-C docs](ObjectiveC.md) for more information and some tips
|
191
|
+
on troubleshooting.
|
189
192
|
|
190
193
|
### Mixed Objective-C / Swift
|
191
194
|
|
@@ -260,6 +263,14 @@ Some examples:
|
|
260
263
|
This implies that `/Build/Products/MyMod.framework` exists and contains
|
261
264
|
a `.swiftmodule`. Again the `--source-directory` is searched by default
|
262
265
|
if `-F` is not passed in.
|
266
|
+
5. With pre-generated symbolgraph files:
|
267
|
+
```shell
|
268
|
+
jazzy --module MyMod --swift-build-tool symbolgraph
|
269
|
+
--symbolgraph-directory Build/symbolgraphs
|
270
|
+
```
|
271
|
+
If you've separately generated symbolgraph files by the use of
|
272
|
+
`-emit-symbol-graph`, you can pass the location of these files using
|
273
|
+
`--symbolgraph-directory` from where they can be parsed directly.
|
263
274
|
|
264
275
|
See `swift symbolgraph-extract -help` for all the things you can pass via
|
265
276
|
`--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).
|
|
408
419
|
environment variable to point to the Xcode you want before running Jazzy
|
409
420
|
without the `--swift-version` flag.
|
410
421
|
|
422
|
+
### Objective-C
|
423
|
+
|
424
|
+
See [this document](ObjectiveC.md).
|
425
|
+
|
411
426
|
### Installation Problems
|
412
427
|
|
413
428
|
**Can't find header files / clang**
|
data/Rakefile
CHANGED
@@ -105,10 +105,12 @@ begin
|
|
105
105
|
desc 'Vendors SourceKitten'
|
106
106
|
task :sourcekitten do
|
107
107
|
sk_dir = 'SourceKitten'
|
108
|
-
Dir.chdir(sk_dir) do
|
109
|
-
|
108
|
+
bin_path = Dir.chdir(sk_dir) do
|
109
|
+
build_cmd = 'swift build -c release --arch arm64 --arch x86_64'
|
110
|
+
`#{build_cmd}`
|
111
|
+
`#{build_cmd} --show-bin-path`.chomp
|
110
112
|
end
|
111
|
-
FileUtils.cp_r "#{
|
113
|
+
FileUtils.cp_r "#{bin_path}/sourcekitten", 'bin'
|
112
114
|
end
|
113
115
|
|
114
116
|
#-- Theme Dependencies -----------------------------------------------------#
|
data/bin/sourcekitten
CHANGED
Binary file
|
data/jazzy.gemspec
CHANGED
@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
|
|
10
10
|
spec.email = ['jp@jpsim.com']
|
11
11
|
spec.summary = 'Soulful docs for Swift & Objective-C.'
|
12
12
|
spec.description = 'Soulful docs for Swift & Objective-C. ' \
|
13
|
-
"Run in your Xcode project's root directory for " \
|
13
|
+
"Run in your SPM or Xcode project's root directory for " \
|
14
14
|
'instant HTML docs.'
|
15
15
|
spec.homepage = 'https://github.com/realm/jazzy'
|
16
16
|
spec.license = 'MIT'
|
@@ -32,4 +32,5 @@ Gem::Specification.new do |spec|
|
|
32
32
|
spec.add_development_dependency 'rake', '~> 13.0'
|
33
33
|
|
34
34
|
spec.required_ruby_version = '>= 2.6.3'
|
35
|
+
spec.metadata['rubygems_mfa_required'] = 'true'
|
35
36
|
end
|
data/lib/jazzy/config.rb
CHANGED
@@ -193,6 +193,12 @@ module Jazzy
|
|
193
193
|
default: Pathname.pwd,
|
194
194
|
parse: ->(sd) { expand_path(sd) }
|
195
195
|
|
196
|
+
config_attr :symbolgraph_directory,
|
197
|
+
command_line: '--symbolgraph-directory DIRPATH',
|
198
|
+
description: 'A directory containing a set of Swift Symbolgraph files ' \
|
199
|
+
'representing the module to be documented',
|
200
|
+
parse: ->(sd) { expand_path(sd) }
|
201
|
+
|
196
202
|
config_attr :excluded_files,
|
197
203
|
command_line: ['-e', '--exclude filepath1,filepath2,…filepathN', Array],
|
198
204
|
description: 'Source file pathnames to be excluded from documentation. '\
|
@@ -591,6 +597,13 @@ module Jazzy
|
|
591
597
|
warning 'Option `source_host` is set but has no effect without either '\
|
592
598
|
'`source_host_url` or `source_host_files_url`.'
|
593
599
|
end
|
600
|
+
|
601
|
+
if objc_mode &&
|
602
|
+
build_tool_arguments_configured &&
|
603
|
+
(framework_root_configured || umbrella_header_configured)
|
604
|
+
warning 'Option `build_tool_arguments` is set: values passed to '\
|
605
|
+
'`framework_root` or `umbrella_header` may be ignored.'
|
606
|
+
end
|
594
607
|
end
|
595
608
|
|
596
609
|
# rubocop:enable Metrics/MethodLength
|
data/lib/jazzy/gem_version.rb
CHANGED
data/lib/jazzy/highlighter.rb
CHANGED
@@ -2,18 +2,6 @@
|
|
2
2
|
|
3
3
|
require 'rouge'
|
4
4
|
|
5
|
-
# While Rouge is downlevel (Rouge PR#1715 unreleased)
|
6
|
-
module Rouge
|
7
|
-
module Lexers
|
8
|
-
class Swift
|
9
|
-
prepend :root do
|
10
|
-
rule(/\b(?:async|await|isolated)\b/, Keyword)
|
11
|
-
rule(/\b(?:actor|nonisolated)\b/, Keyword::Declaration)
|
12
|
-
end
|
13
|
-
end
|
14
|
-
end
|
15
|
-
end
|
16
|
-
|
17
5
|
module Jazzy
|
18
6
|
# This module helps highlight code
|
19
7
|
module Highlighter
|
data/lib/jazzy/search_builder.rb
CHANGED
@@ -6,17 +6,15 @@ module Jazzy
|
|
6
6
|
decls = source_module.all_declarations.select do |d|
|
7
7
|
d.type && d.name && !d.name.empty?
|
8
8
|
end
|
9
|
-
index = decls.
|
9
|
+
index = decls.to_h do |d|
|
10
10
|
[d.url,
|
11
11
|
{
|
12
12
|
name: d.name,
|
13
13
|
abstract: d.abstract && d.abstract.split(/\n/).map(&:strip).first,
|
14
|
-
parent_name: d.parent_in_code
|
14
|
+
parent_name: d.parent_in_code&.name,
|
15
15
|
}.reject { |_, v| v.nil? || v.empty? }]
|
16
|
-
end.to_h
|
17
|
-
File.open(File.join(output_dir, 'search.json'), 'w') do |f|
|
18
|
-
f.write(index.to_json)
|
19
16
|
end
|
17
|
+
File.write(File.join(output_dir, 'search.json'), index.to_json)
|
20
18
|
end
|
21
19
|
end
|
22
20
|
end
|
@@ -183,10 +183,12 @@ module Jazzy
|
|
183
183
|
inherited_types.any? { |t| !unwanted.include?(t) }
|
184
184
|
end
|
185
185
|
|
186
|
-
# SourceKit only sets modulename for imported modules
|
186
|
+
# Pre-Swift 5.6: SourceKit only sets modulename for imported modules
|
187
|
+
# Swift 5.6+: modulename is always set
|
187
188
|
def type_from_doc_module?
|
188
189
|
!type.extension? ||
|
189
|
-
(swift? && usr &&
|
190
|
+
(swift? && usr &&
|
191
|
+
(modulename.nil? || modulename == Config.instance.module_name))
|
190
192
|
end
|
191
193
|
|
192
194
|
# Info text for contents page by collapsed item name
|
data/lib/jazzy/sourcekitten.rb
CHANGED
@@ -355,7 +355,9 @@ module Jazzy
|
|
355
355
|
# Call things undocumented if they were compiled properly
|
356
356
|
# and came from our module.
|
357
357
|
def self.should_mark_undocumented(declaration)
|
358
|
-
declaration.usr &&
|
358
|
+
declaration.usr &&
|
359
|
+
(declaration.modulename.nil? ||
|
360
|
+
declaration.modulename == Config.instance.module_name)
|
359
361
|
end
|
360
362
|
|
361
363
|
def self.process_undocumented_token(doc, declaration)
|
data/lib/jazzy/symbol_graph.rb
CHANGED
@@ -14,27 +14,24 @@ require 'jazzy/symbol_graph/ext_node'
|
|
14
14
|
|
15
15
|
module Jazzy
|
16
16
|
module SymbolGraph
|
17
|
-
#
|
18
|
-
#
|
17
|
+
# Find swift symbol graph files, either having been passed
|
18
|
+
# in directly, or generated by running`swift symbolgraph-extract`
|
19
|
+
# with configured args.
|
20
|
+
# Then parse the results, and return as JSON in SourceKit[ten]
|
19
21
|
# format.
|
20
22
|
def self.build(config)
|
21
|
-
|
22
|
-
|
23
|
+
if config.symbolgraph_directory.nil?
|
24
|
+
Dir.mktmpdir do |tmp_dir|
|
25
|
+
args = arguments(config, tmp_dir)
|
23
26
|
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
+
Executable.execute_command('swift',
|
28
|
+
args.unshift('symbolgraph-extract'),
|
29
|
+
true) # raise on error
|
27
30
|
|
28
|
-
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
module_name = Regexp.last_match[3] || Regexp.last_match[1]
|
33
|
-
{
|
34
|
-
filename =>
|
35
|
-
Graph.new(File.read(filename), module_name).to_sourcekit,
|
36
|
-
}
|
37
|
-
end.to_json
|
31
|
+
parse_symbols(tmp_dir)
|
32
|
+
end
|
33
|
+
else
|
34
|
+
parse_symbols(config.symbolgraph_directory.to_s)
|
38
35
|
end
|
39
36
|
end
|
40
37
|
|
@@ -69,6 +66,20 @@ module Jazzy
|
|
69
66
|
args + config.build_tool_arguments
|
70
67
|
end
|
71
68
|
|
69
|
+
# Parse the symbol files in the given directory
|
70
|
+
def self.parse_symbols(directory)
|
71
|
+
Dir[directory + '/*.symbols.json'].map do |filename|
|
72
|
+
# The @ part is for extensions in our module (before the @)
|
73
|
+
# of types in another module (after the @).
|
74
|
+
File.basename(filename) =~ /(.*?)(@(.*?))?\.symbols/
|
75
|
+
module_name = Regexp.last_match[3] || Regexp.last_match[1]
|
76
|
+
{
|
77
|
+
filename =>
|
78
|
+
Graph.new(File.read(filename), module_name).to_sourcekit,
|
79
|
+
}
|
80
|
+
end.to_json
|
81
|
+
end
|
82
|
+
|
72
83
|
# Get the SDK path. On !darwin this just isn't needed.
|
73
84
|
def self.sdk(config)
|
74
85
|
`xcrun --show-sdk-path --sdk #{config.sdk}`.chomp
|
data/spec/integration_spec.rb
CHANGED
@@ -85,9 +85,8 @@ CLIntegracon.configure do |c|
|
|
85
85
|
|
86
86
|
# Transform produced databases to csv
|
87
87
|
c.transform_produced '**/*.dsidx' do |path|
|
88
|
-
File.
|
89
|
-
|
90
|
-
end
|
88
|
+
File.write("#{path}.csv",
|
89
|
+
`sqlite3 -header -csv #{path} "select * from searchIndex;"`)
|
91
90
|
end
|
92
91
|
# Now that we're comparing the CSV, we don't care about the binary
|
93
92
|
c.ignores '**/*.dsidx'
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: jazzy
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.14.
|
4
|
+
version: 0.14.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- JP Simard
|
@@ -11,7 +11,7 @@ authors:
|
|
11
11
|
autorequire:
|
12
12
|
bindir: bin
|
13
13
|
cert_chain: []
|
14
|
-
date:
|
14
|
+
date: 2022-03-17 00:00:00.000000000 Z
|
15
15
|
dependencies:
|
16
16
|
- !ruby/object:Gem::Dependency
|
17
17
|
name: cocoapods
|
@@ -173,8 +173,8 @@ dependencies:
|
|
173
173
|
- - "~>"
|
174
174
|
- !ruby/object:Gem::Version
|
175
175
|
version: '13.0'
|
176
|
-
description: Soulful docs for Swift & Objective-C. Run in your Xcode project's
|
177
|
-
directory for instant HTML docs.
|
176
|
+
description: Soulful docs for Swift & Objective-C. Run in your SPM or Xcode project's
|
177
|
+
root directory for instant HTML docs.
|
178
178
|
email:
|
179
179
|
- jp@jpsim.com
|
180
180
|
executables:
|
@@ -192,6 +192,7 @@ files:
|
|
192
192
|
- Gemfile
|
193
193
|
- Gemfile.lock
|
194
194
|
- LICENSE
|
195
|
+
- ObjectiveC.md
|
195
196
|
- README.md
|
196
197
|
- Rakefile
|
197
198
|
- bin/jazzy
|
@@ -354,7 +355,8 @@ files:
|
|
354
355
|
homepage: https://github.com/realm/jazzy
|
355
356
|
licenses:
|
356
357
|
- MIT
|
357
|
-
metadata:
|
358
|
+
metadata:
|
359
|
+
rubygems_mfa_required: 'true'
|
358
360
|
post_install_message:
|
359
361
|
rdoc_options: []
|
360
362
|
require_paths:
|