jazzy 0.13.5 → 0.13.6
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.circleci/config.yml +6 -3
- data/CHANGELOG.md +18 -0
- data/Gemfile.lock +35 -35
- data/README.md +57 -4
- data/bin/sourcekitten +0 -0
- data/lib/jazzy/config.rb +5 -5
- data/lib/jazzy/doc_builder.rb +7 -1
- data/lib/jazzy/gem_version.rb +1 -1
- data/lib/jazzy/sourcekitten.rb +5 -6
- data/lib/jazzy/symbol_graph.rb +95 -0
- data/lib/jazzy/symbol_graph/constraint.rb +94 -0
- data/lib/jazzy/symbol_graph/ext_node.rb +114 -0
- data/lib/jazzy/symbol_graph/graph.rb +193 -0
- data/lib/jazzy/symbol_graph/relationship.rb +39 -0
- data/lib/jazzy/symbol_graph/sym_node.rb +154 -0
- data/lib/jazzy/symbol_graph/symbol.rb +208 -0
- data/spec/integration_spec.rb +17 -8
- metadata +13 -7
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 20ab471420ed44e905319be51f0410c0571efa3f56902834b6e7d47f4f66fd0a
|
4
|
+
data.tar.gz: 2bfa14b53c563edb51d4cf0f0a4041859929561b725324761f17568410819838
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 6c5b2eeb4b88f7cf4c8b406bc627c754b50f7f95cd9c555127998530e201b7dfc0e86c237cff3f3dff71c85fa6c979733e0b75de6fd4c52333de8e9d9cf741b0
|
7
|
+
data.tar.gz: 672470f7c618f5fc659035a2705674b3804558abc86d58c788943f1495e7e4e3de9447ae6ee46156b68c11776d32986551c91a7f7b222fda455e59f89bc91973
|
data/.circleci/config.yml
CHANGED
@@ -17,11 +17,12 @@ jobs:
|
|
17
17
|
|
18
18
|
swift:
|
19
19
|
macos:
|
20
|
-
xcode: "
|
20
|
+
xcode: "12.1.0"
|
21
21
|
environment: *bundler-environment
|
22
22
|
steps:
|
23
23
|
- checkout
|
24
24
|
- restore_cache: *restore-mac-bundler-cache
|
25
|
+
- run: echo 'chruby 2.6' >> ~/.bash_profile
|
25
26
|
- run: bundle install
|
26
27
|
- run: git submodule update --init --recursive
|
27
28
|
- run: bundle exec rake swift_spec
|
@@ -29,11 +30,12 @@ jobs:
|
|
29
30
|
|
30
31
|
objc:
|
31
32
|
macos:
|
32
|
-
xcode: "
|
33
|
+
xcode: "12.1.0"
|
33
34
|
environment: *bundler-environment
|
34
35
|
steps:
|
35
36
|
- checkout
|
36
37
|
- restore_cache: *restore-mac-bundler-cache
|
38
|
+
- run: echo 'chruby 2.6' >> ~/.bash_profile
|
37
39
|
- run: bundle install
|
38
40
|
- run: git submodule update --init --recursive
|
39
41
|
- run: bundle exec rake objc_spec
|
@@ -41,13 +43,14 @@ jobs:
|
|
41
43
|
|
42
44
|
cocoapods:
|
43
45
|
macos:
|
44
|
-
xcode: "
|
46
|
+
xcode: "12.1.0"
|
45
47
|
environment: *bundler-environment
|
46
48
|
steps:
|
47
49
|
- checkout
|
48
50
|
- restore_cache:
|
49
51
|
key: cocoapods
|
50
52
|
- restore_cache: *restore-mac-bundler-cache
|
53
|
+
- run: echo 'chruby 2.6' >> ~/.bash_profile
|
51
54
|
- run: bundle install
|
52
55
|
- run: git submodule update --init --recursive
|
53
56
|
- run: bundle exec rake cocoapods_spec
|
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,21 @@
|
|
1
|
+
## 0.13.6
|
2
|
+
|
3
|
+
##### Breaking
|
4
|
+
|
5
|
+
* None.
|
6
|
+
|
7
|
+
##### Enhancements
|
8
|
+
|
9
|
+
* Support documentation generation from `.swiftmodule` binaries using
|
10
|
+
`--swift-build-tool symbolgraph` with Swift 5.3.
|
11
|
+
[John Fairhurst](https://github.com/johnfairh)
|
12
|
+
|
13
|
+
##### Bug Fixes
|
14
|
+
|
15
|
+
* Always bypass codesigning when building Xcode projects.
|
16
|
+
[John Fairhurst](https://github.com/johnfairh)
|
17
|
+
[#1183](https://github.com/realm/jazzy/issues/1183)
|
18
|
+
|
1
19
|
## 0.13.5
|
2
20
|
|
3
21
|
##### Breaking
|
data/Gemfile.lock
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
PATH
|
2
2
|
remote: .
|
3
3
|
specs:
|
4
|
-
jazzy (0.13.
|
4
|
+
jazzy (0.13.6)
|
5
5
|
cocoapods (~> 1.5)
|
6
6
|
mustache (~> 1.1)
|
7
7
|
open4
|
@@ -15,14 +15,14 @@ GEM
|
|
15
15
|
remote: https://rubygems.org/
|
16
16
|
specs:
|
17
17
|
CFPropertyList (3.0.2)
|
18
|
-
activesupport (
|
19
|
-
|
18
|
+
activesupport (5.2.4.4)
|
19
|
+
concurrent-ruby (~> 1.0, >= 1.0.2)
|
20
|
+
i18n (>= 0.7, < 2)
|
20
21
|
minitest (~> 5.1)
|
21
|
-
thread_safe (~> 0.3, >= 0.3.4)
|
22
22
|
tzinfo (~> 1.1)
|
23
23
|
addressable (2.7.0)
|
24
24
|
public_suffix (>= 2.0.2, < 5.0)
|
25
|
-
algoliasearch (1.27.
|
25
|
+
algoliasearch (1.27.5)
|
26
26
|
httpclient (~> 2.8, >= 2.8.3)
|
27
27
|
json (>= 1.5.1)
|
28
28
|
ast (2.4.1)
|
@@ -36,15 +36,14 @@ GEM
|
|
36
36
|
clintegracon (0.7.0)
|
37
37
|
colored (~> 1.2)
|
38
38
|
diffy
|
39
|
-
cocoapods (1.
|
40
|
-
|
39
|
+
cocoapods (1.10.0)
|
40
|
+
addressable (~> 2.6)
|
41
41
|
claide (>= 1.0.2, < 2.0)
|
42
|
-
cocoapods-core (= 1.
|
42
|
+
cocoapods-core (= 1.10.0)
|
43
43
|
cocoapods-deintegrate (>= 1.0.3, < 2.0)
|
44
|
-
cocoapods-downloader (>= 1.
|
44
|
+
cocoapods-downloader (>= 1.4.0, < 2.0)
|
45
45
|
cocoapods-plugins (>= 1.0.0, < 2.0)
|
46
46
|
cocoapods-search (>= 1.0.0, < 2.0)
|
47
|
-
cocoapods-stats (>= 1.0.0, < 2.0)
|
48
47
|
cocoapods-trunk (>= 1.4.0, < 2.0)
|
49
48
|
cocoapods-try (>= 1.1.0, < 2.0)
|
50
49
|
colored2 (~> 3.1)
|
@@ -54,33 +53,33 @@ GEM
|
|
54
53
|
molinillo (~> 0.6.6)
|
55
54
|
nap (~> 1.0)
|
56
55
|
ruby-macho (~> 1.4)
|
57
|
-
xcodeproj (>= 1.
|
58
|
-
cocoapods-core (1.
|
59
|
-
activesupport (
|
56
|
+
xcodeproj (>= 1.19.0, < 2.0)
|
57
|
+
cocoapods-core (1.10.0)
|
58
|
+
activesupport (> 5.0, < 6)
|
59
|
+
addressable (~> 2.6)
|
60
60
|
algoliasearch (~> 1.0)
|
61
61
|
concurrent-ruby (~> 1.1)
|
62
62
|
fuzzy_match (~> 2.0.4)
|
63
63
|
nap (~> 1.0)
|
64
64
|
netrc (~> 0.11)
|
65
|
+
public_suffix
|
65
66
|
typhoeus (~> 1.0)
|
66
67
|
cocoapods-deintegrate (1.0.4)
|
67
|
-
cocoapods-downloader (1.
|
68
|
+
cocoapods-downloader (1.4.0)
|
68
69
|
cocoapods-plugins (1.0.0)
|
69
70
|
nap
|
70
71
|
cocoapods-search (1.0.0)
|
71
|
-
cocoapods-stats (1.1.0)
|
72
72
|
cocoapods-trunk (1.5.0)
|
73
73
|
nap (>= 0.8, < 2.0)
|
74
74
|
netrc (~> 0.11)
|
75
75
|
cocoapods-try (1.2.0)
|
76
76
|
colored (1.2)
|
77
77
|
colored2 (3.1.2)
|
78
|
-
concurrent-ruby (1.1.
|
78
|
+
concurrent-ruby (1.1.7)
|
79
79
|
cork (0.3.0)
|
80
80
|
colored2 (~> 3.1)
|
81
|
-
crack (0.4.
|
82
|
-
|
83
|
-
danger (8.0.2)
|
81
|
+
crack (0.4.4)
|
82
|
+
danger (8.2.0)
|
84
83
|
claide (~> 1.0)
|
85
84
|
claide-plugins (>= 0.9.2)
|
86
85
|
colored2 (~> 3.1)
|
@@ -88,17 +87,18 @@ GEM
|
|
88
87
|
faraday (>= 0.9.0, < 2.0)
|
89
88
|
faraday-http-cache (~> 2.0)
|
90
89
|
git (~> 1.7)
|
91
|
-
kramdown (~> 2.
|
90
|
+
kramdown (~> 2.3)
|
92
91
|
kramdown-parser-gfm (~> 1.0)
|
93
92
|
no_proxy_fix
|
94
93
|
octokit (~> 4.7)
|
95
94
|
terminal-table (~> 1)
|
96
|
-
diffy (3.
|
95
|
+
diffy (3.4.0)
|
97
96
|
escape (0.0.4)
|
98
97
|
ethon (0.12.0)
|
99
98
|
ffi (>= 1.3.0)
|
100
|
-
faraday (1.0
|
99
|
+
faraday (1.1.0)
|
101
100
|
multipart-post (>= 1.2, < 3)
|
101
|
+
ruby2_keywords
|
102
102
|
faraday-http-cache (2.2.0)
|
103
103
|
faraday (>= 0.8)
|
104
104
|
ffi (1.13.1)
|
@@ -109,7 +109,7 @@ GEM
|
|
109
109
|
rchardet (~> 1.8)
|
110
110
|
hashdiff (1.0.1)
|
111
111
|
httpclient (2.8.3)
|
112
|
-
i18n (
|
112
|
+
i18n (1.8.5)
|
113
113
|
concurrent-ruby (~> 1.0)
|
114
114
|
json (2.3.1)
|
115
115
|
kramdown (2.3.0)
|
@@ -117,35 +117,35 @@ GEM
|
|
117
117
|
kramdown-parser-gfm (1.1.0)
|
118
118
|
kramdown (~> 2.0)
|
119
119
|
liferaft (0.0.6)
|
120
|
-
minitest (5.14.
|
120
|
+
minitest (5.14.2)
|
121
121
|
mocha (1.11.2)
|
122
122
|
mocha-on-bacon (0.2.3)
|
123
123
|
mocha (>= 0.13.0)
|
124
124
|
molinillo (0.6.6)
|
125
125
|
multipart-post (2.1.1)
|
126
126
|
mustache (1.1.1)
|
127
|
-
nanaimo (0.
|
127
|
+
nanaimo (0.3.0)
|
128
128
|
nap (1.1.0)
|
129
129
|
netrc (0.11.0)
|
130
130
|
no_proxy_fix (0.1.2)
|
131
|
-
octokit (4.
|
131
|
+
octokit (4.19.0)
|
132
132
|
faraday (>= 0.9)
|
133
133
|
sawyer (~> 0.8.0, >= 0.5.3)
|
134
134
|
open4 (1.3.4)
|
135
|
-
parallel (1.
|
136
|
-
parser (2.7.
|
135
|
+
parallel (1.20.0)
|
136
|
+
parser (2.7.2.0)
|
137
137
|
ast (~> 2.4.1)
|
138
138
|
powerpack (0.1.2)
|
139
139
|
prettybacon (0.0.2)
|
140
140
|
bacon (~> 1.2)
|
141
|
-
public_suffix (4.0.
|
141
|
+
public_suffix (4.0.6)
|
142
142
|
rainbow (2.2.2)
|
143
143
|
rake
|
144
144
|
rake (13.0.1)
|
145
145
|
rchardet (1.8.0)
|
146
146
|
redcarpet (3.5.0)
|
147
147
|
rexml (3.2.4)
|
148
|
-
rouge (3.
|
148
|
+
rouge (3.24.0)
|
149
149
|
rubocop (0.49.0)
|
150
150
|
parallel (~> 1.10)
|
151
151
|
parser (>= 2.3.3.1, < 3.0)
|
@@ -155,7 +155,7 @@ GEM
|
|
155
155
|
unicode-display_width (~> 1.0, >= 1.0.1)
|
156
156
|
ruby-macho (1.4.0)
|
157
157
|
ruby-progressbar (1.10.1)
|
158
|
-
|
158
|
+
ruby2_keywords (0.0.2)
|
159
159
|
sassc (2.4.0)
|
160
160
|
ffi (~> 1.9)
|
161
161
|
sawyer (0.8.2)
|
@@ -167,21 +167,21 @@ GEM
|
|
167
167
|
thread_safe (0.3.6)
|
168
168
|
typhoeus (1.4.0)
|
169
169
|
ethon (>= 0.9.0)
|
170
|
-
tzinfo (1.2.
|
170
|
+
tzinfo (1.2.8)
|
171
171
|
thread_safe (~> 0.1)
|
172
172
|
unicode-display_width (1.7.0)
|
173
|
-
webmock (3.
|
173
|
+
webmock (3.9.4)
|
174
174
|
addressable (>= 2.3.6)
|
175
175
|
crack (>= 0.3.2)
|
176
176
|
hashdiff (>= 0.4.0, < 2.0.0)
|
177
177
|
xcinvoke (0.3.0)
|
178
178
|
liferaft (~> 0.0.6)
|
179
|
-
xcodeproj (1.
|
179
|
+
xcodeproj (1.19.0)
|
180
180
|
CFPropertyList (>= 2.3.3, < 4.0)
|
181
181
|
atomos (~> 0.1.3)
|
182
182
|
claide (>= 1.0.2, < 2.0)
|
183
183
|
colored2 (~> 3.1)
|
184
|
-
nanaimo (~> 0.
|
184
|
+
nanaimo (~> 0.3.0)
|
185
185
|
|
186
186
|
PLATFORMS
|
187
187
|
ruby
|
data/README.md
CHANGED
@@ -8,13 +8,14 @@
|
|
8
8
|
|
9
9
|
Both Swift and Objective-C projects are supported.
|
10
10
|
|
11
|
-
*SwiftPM support was recently added, so please report any issues you find.*
|
12
|
-
|
13
11
|
Instead of parsing your source files, `jazzy` hooks into [Clang][clang] and
|
14
12
|
[SourceKit][sourcekit] to use the [AST][ast] representation of your code and
|
15
13
|
its comments for more accurate results. The output matches the look and feel
|
16
14
|
of Apple’s official reference documentation, post WWDC 2014.
|
17
15
|
|
16
|
+
Jazzy can also generate documentation from compiled swift modules [using their
|
17
|
+
symbol graph](#docs-from-swiftmodules-or-frameworks) instead of source code.
|
18
|
+
|
18
19
|
![Screenshot](images/screenshot.jpg)
|
19
20
|
|
20
21
|
This project adheres to the [Contributor Covenant Code of Conduct](https://realm.io/conduct).
|
@@ -49,13 +50,14 @@ succeed too!
|
|
49
50
|
|
50
51
|
If Jazzy generates docs for the wrong module then use `--module` to tell it which
|
51
52
|
one you'd prefer. If this doesn't help, and you're using Xcode, then try passing
|
52
|
-
extra arguments to `xcodebuild`, for example
|
53
|
+
extra arguments to `xcodebuild`, for example
|
54
|
+
`jazzy --build-tool-arguments -scheme,MyScheme,-target,MyTarget`.
|
53
55
|
|
54
56
|
You can set options for your project’s documentation in a configuration file,
|
55
57
|
`.jazzy.yaml` by default. For a detailed explanation and an exhaustive list of
|
56
58
|
all available options, run `jazzy --help config`.
|
57
59
|
|
58
|
-
### Supported keywords
|
60
|
+
### Supported documentation keywords
|
59
61
|
|
60
62
|
Swift documentation is written in markdown and supports a number of special keywords.
|
61
63
|
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/),
|
@@ -200,6 +202,57 @@ sourcekitten doc --objc $(pwd)/MyProject/MyProject.h \
|
|
200
202
|
jazzy --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
|
201
203
|
```
|
202
204
|
|
205
|
+
### Docs from `.swiftmodule`s or frameworks
|
206
|
+
|
207
|
+
*This feature is new and relies on a new Swift feature: there may be crashes
|
208
|
+
and mistakes: reports welcome.*
|
209
|
+
|
210
|
+
Swift 5.3 adds support for symbol graph generation from `.swiftmodule` files.
|
211
|
+
This looks to be part of Apple's toolchain for generating their online docs.
|
212
|
+
|
213
|
+
Jazzy can use this to generate API documentation. This is faster than using
|
214
|
+
the source code directly but does have limitations: for example documentation
|
215
|
+
comments are available only for `public` declarations, and the presentation of
|
216
|
+
Swift extensions may not match the way they are written in code.
|
217
|
+
|
218
|
+
Some examples:
|
219
|
+
|
220
|
+
1. Generate docs for the Apple Combine framework for macOS:
|
221
|
+
```shell
|
222
|
+
jazzy --module Combine --swift-build-tool symbolgraph
|
223
|
+
```
|
224
|
+
The SDK's library directories are included in the search path by
|
225
|
+
default.
|
226
|
+
2. Same but for iOS:
|
227
|
+
```shell
|
228
|
+
jazzy --module Combine --swift-build-tool symbolgraph
|
229
|
+
--sdk iphoneos
|
230
|
+
--build-tool-arguments --target,arm64-apple-ios14.1
|
231
|
+
```
|
232
|
+
The `target` is the LLVM target triple and needs to match the SDK. The
|
233
|
+
default here is the target of the host system that Jazzy is running on,
|
234
|
+
something like `x86_64-apple-darwin19.6.0`.
|
235
|
+
3. Generate docs for a personal `.swiftmodule`:
|
236
|
+
```shell
|
237
|
+
jazzy --module MyMod --swift-build-tool symbolgraph
|
238
|
+
--build-tool-arguments -I,/Build/Products
|
239
|
+
```
|
240
|
+
This implies that `/Build/Products/MyMod.swiftmodule` exists. Jazzy's
|
241
|
+
`--source-directory` (default current directory) is searched by default,
|
242
|
+
so you only need the `-I` override if that's not enough.
|
243
|
+
4. For a personal framework:
|
244
|
+
```shell
|
245
|
+
jazzy --module MyMod --swift-build-tool symbolgraph
|
246
|
+
--build-tool-arguments -F,/Build/Products
|
247
|
+
```
|
248
|
+
This implies that `/Build/Products/MyMod.framework` exists and contains
|
249
|
+
a `.swiftmodule`. Again the `--source-directory` is searched by default
|
250
|
+
if `-F` is not passed in.
|
251
|
+
|
252
|
+
See `swift symbolgraph-extract --help` for all the things you can pass via
|
253
|
+
`--build-tool-arguments`: if your module has dependencies then you may need
|
254
|
+
to add various search path options to let Swift load it.
|
255
|
+
|
203
256
|
### Themes
|
204
257
|
|
205
258
|
Three themes are provided with jazzy: `apple` (default), `fullwidth` and `jony`.
|
data/bin/sourcekitten
CHANGED
Binary file
|
data/lib/jazzy/config.rb
CHANGED
@@ -219,14 +219,14 @@ module Jazzy
|
|
219
219
|
end
|
220
220
|
end
|
221
221
|
|
222
|
-
SWIFT_BUILD_TOOLS = %w[spm xcodebuild].freeze
|
222
|
+
SWIFT_BUILD_TOOLS = %w[spm xcodebuild symbolgraph].freeze
|
223
223
|
|
224
224
|
config_attr :swift_build_tool,
|
225
225
|
command_line: "--swift-build-tool #{SWIFT_BUILD_TOOLS.join(' | ')}",
|
226
|
-
description: 'Control whether Jazzy uses Swift Package Manager
|
227
|
-
'xcodebuild to build the module
|
228
|
-
'default it uses xcodebuild if
|
229
|
-
'file in the source directory.',
|
226
|
+
description: 'Control whether Jazzy uses Swift Package Manager, '\
|
227
|
+
'xcodebuild, or swift-symbolgraph to build the module '\
|
228
|
+
'to be documented. By default it uses xcodebuild if '\
|
229
|
+
'there is a .xcodeproj file in the source directory.',
|
230
230
|
parse: ->(tool) do
|
231
231
|
return tool.to_sym if SWIFT_BUILD_TOOLS.include?(tool)
|
232
232
|
raise "Unsupported swift_build_tool #{tool}, "\
|
data/lib/jazzy/doc_builder.rb
CHANGED
@@ -14,6 +14,7 @@ require 'jazzy/source_declaration'
|
|
14
14
|
require 'jazzy/source_document'
|
15
15
|
require 'jazzy/source_module'
|
16
16
|
require 'jazzy/sourcekitten'
|
17
|
+
require 'jazzy/symbol_graph'
|
17
18
|
|
18
19
|
module Jazzy
|
19
20
|
# This module handles HTML generation, file writing, asset copying,
|
@@ -72,6 +73,8 @@ module Jazzy
|
|
72
73
|
elsif options.podspec_configured
|
73
74
|
pod_documenter = PodspecDocumenter.new(options.podspec)
|
74
75
|
stdout = pod_documenter.sourcekitten_output(options)
|
76
|
+
elsif options.swift_build_tool == :symbolgraph
|
77
|
+
stdout = SymbolGraph.build(options)
|
75
78
|
else
|
76
79
|
stdout = Dir.chdir(options.source_directory) do
|
77
80
|
arguments = SourceKitten.arguments_from_options(options)
|
@@ -192,7 +195,10 @@ module Jazzy
|
|
192
195
|
|
193
196
|
lint_report = {
|
194
197
|
warnings: warnings.sort_by do |w|
|
195
|
-
[w[:file]
|
198
|
+
[w[:file] || Pathname(''),
|
199
|
+
w[:line] || 0,
|
200
|
+
w[:symbol],
|
201
|
+
w[:symbol_kind]]
|
196
202
|
end,
|
197
203
|
source_directory: options.source_directory,
|
198
204
|
}
|
data/lib/jazzy/gem_version.rb
CHANGED
data/lib/jazzy/sourcekitten.rb
CHANGED
@@ -325,17 +325,16 @@ module Jazzy
|
|
325
325
|
end
|
326
326
|
end
|
327
327
|
|
328
|
-
|
329
|
-
|
330
|
-
|
328
|
+
# Call things undocumented if they were compiled properly
|
329
|
+
# and came from our module.
|
330
|
+
def self.should_mark_undocumented(declaration)
|
331
|
+
declaration.usr && !declaration.modulename
|
331
332
|
end
|
332
333
|
|
333
334
|
def self.process_undocumented_token(doc, declaration)
|
334
335
|
make_default_doc_info(declaration)
|
335
336
|
|
336
|
-
|
337
|
-
|
338
|
-
if !declaration.swift? || should_mark_undocumented(filepath)
|
337
|
+
if !declaration.swift? || should_mark_undocumented(declaration)
|
339
338
|
@stats.add_undocumented(declaration)
|
340
339
|
return nil if @skip_undocumented
|
341
340
|
declaration.abstract = undocumented_abstract
|
@@ -0,0 +1,95 @@
|
|
1
|
+
require 'set'
|
2
|
+
require 'jazzy/symbol_graph/graph'
|
3
|
+
require 'jazzy/symbol_graph/constraint'
|
4
|
+
require 'jazzy/symbol_graph/symbol'
|
5
|
+
require 'jazzy/symbol_graph/relationship'
|
6
|
+
require 'jazzy/symbol_graph/sym_node'
|
7
|
+
require 'jazzy/symbol_graph/ext_node'
|
8
|
+
|
9
|
+
# This is the top-level symbolgraph driver that deals with
|
10
|
+
# figuring out arguments, running the tool, and loading the
|
11
|
+
# results.
|
12
|
+
|
13
|
+
module Jazzy
|
14
|
+
module SymbolGraph
|
15
|
+
# Run `swift symbolgraph-extract` with configured args,
|
16
|
+
# parse the results, and return as JSON in SourceKit[ten]
|
17
|
+
# format.
|
18
|
+
def self.build(config)
|
19
|
+
Dir.mktmpdir do |tmp_dir|
|
20
|
+
args = arguments(config, tmp_dir)
|
21
|
+
|
22
|
+
Executable.execute_command('swift',
|
23
|
+
args.unshift('symbolgraph-extract'),
|
24
|
+
true) # raise on error
|
25
|
+
|
26
|
+
Dir[tmp_dir + '/*.symbols.json'].map do |filename|
|
27
|
+
# The @ part is for extensions in our module (before the @)
|
28
|
+
# of types in another module (after the @).
|
29
|
+
filename =~ /(.*?)(@(.*?))?\.symbols/
|
30
|
+
module_name = Regexp.last_match[3] || Regexp.last_match[1]
|
31
|
+
{
|
32
|
+
filename =>
|
33
|
+
Graph.new(File.read(filename), module_name).to_sourcekit,
|
34
|
+
}
|
35
|
+
end.to_json
|
36
|
+
end
|
37
|
+
end
|
38
|
+
|
39
|
+
# Figure out the args to pass to symbolgraph-extract
|
40
|
+
# rubocop:disable Metrics/CyclomaticComplexity
|
41
|
+
def self.arguments(config, output_path)
|
42
|
+
if config.module_name.empty?
|
43
|
+
raise 'error: `--swift-build-tool symbolgraph` requires `--module`.'
|
44
|
+
end
|
45
|
+
|
46
|
+
user_args = config.build_tool_arguments.join
|
47
|
+
|
48
|
+
if user_args =~ /--(?:module-name|minimum-access-level|output-dir)/
|
49
|
+
raise 'error: `--build-tool-arguments` for '\
|
50
|
+
"`--swift-build-tool symbolgraph` can't use `--module`, "\
|
51
|
+
'`--minimum-access-level`, or `--output-dir`.'
|
52
|
+
end
|
53
|
+
|
54
|
+
# Default set
|
55
|
+
args = [
|
56
|
+
"--module-name=#{config.module_name}",
|
57
|
+
'--minimum-access-level=private',
|
58
|
+
"--output-dir=#{output_path}",
|
59
|
+
'--skip-synthesized-members',
|
60
|
+
]
|
61
|
+
|
62
|
+
# Things user can override
|
63
|
+
args.append("--sdk=#{sdk(config)}") unless user_args =~ /--sdk/
|
64
|
+
args.append("--target=#{target}") unless user_args =~ /--target/
|
65
|
+
args.append("-F=#{config.source_directory}") unless user_args =~ /-F(?!s)/
|
66
|
+
args.append("-I=#{config.source_directory}") unless user_args =~ /-I/
|
67
|
+
|
68
|
+
args + config.build_tool_arguments
|
69
|
+
end
|
70
|
+
# rubocop:enable Metrics/CyclomaticComplexity
|
71
|
+
|
72
|
+
# Get the SDK path. On !darwin this just isn't needed.
|
73
|
+
def self.sdk(config)
|
74
|
+
`xcrun --show-sdk-path --sdk #{config.sdk}`.chomp
|
75
|
+
end
|
76
|
+
|
77
|
+
# Guess a default LLVM target. Feels like the tool should figure this
|
78
|
+
# out from sdk + the binary somehow?
|
79
|
+
def self.target
|
80
|
+
`swift -version` =~ /Target: (.*?)$/
|
81
|
+
Regexp.last_match[1] || 'x86_64-apple-macosx10.15'
|
82
|
+
end
|
83
|
+
|
84
|
+
# This is a last-ditch fallback for when symbolgraph doesn't
|
85
|
+
# provide a name - at least conforming external types to local
|
86
|
+
# protocols.
|
87
|
+
def self.demangle(usr)
|
88
|
+
args = %w[demangle -simplified -compact].append(usr.sub(/^s:/, 's'))
|
89
|
+
output, = Executable.execute_command('swift', args, true)
|
90
|
+
return output.chomp
|
91
|
+
rescue
|
92
|
+
usr
|
93
|
+
end
|
94
|
+
end
|
95
|
+
end
|