jazzy 0.7.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +29 -0
- data/Gemfile.lock +1 -1
- data/README.md +1 -1
- data/lib/jazzy/SourceKitten/Rakefile +2 -0
- data/lib/jazzy/config.rb +3 -2
- data/lib/jazzy/doc_builder.rb +16 -59
- data/lib/jazzy/gem_version.rb +1 -1
- data/lib/jazzy/source_declaration.rb +1 -0
- data/lib/jazzy/source_declaration/access_control_level.rb +23 -4
- data/lib/jazzy/sourcekitten.rb +16 -11
- data/spec/integration_spec.rb +9 -0
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 407cbe5270841f8ec4c1f0bce108b166a11dbf20
|
4
|
+
data.tar.gz: 5e36875d2c77dae45f19aeb501b5db4ef6b9c1b7
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 3b39e6b6c7039637d51ab118ff1d2d53e4fff1fe2ca4106d261d75d437f0fbce26430c81b46a0a13d984566d98b1a95403243d271d08453f2e1dfdaea57f79ed
|
7
|
+
data.tar.gz: f76fe47dd5d5c91b556a7265e72a37cc38aa8f561282db1c9455aa981b36081ccafc839ce5b5c76b60df111ed7138ba1eaf79d9905a9c974012b179ae16af13b
|
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,32 @@
|
|
1
|
+
## 0.7.1
|
2
|
+
|
3
|
+
##### Breaking
|
4
|
+
|
5
|
+
* None.
|
6
|
+
|
7
|
+
##### Enhancements
|
8
|
+
|
9
|
+
* Added support for the new access control specifiers of fileprivate and open.
|
10
|
+
[Shmuel Kallner](https://github.com/shmuelk)
|
11
|
+
[#645](https://github.com/realm/jazzy/issues/645)
|
12
|
+
[#646](https://github.com/realm/jazzy/issues/646)
|
13
|
+
|
14
|
+
##### Bug Fixes
|
15
|
+
|
16
|
+
* Fix issue where jazzy could not be installed from Gemfile due to
|
17
|
+
SourceKitten symlinks already being present.
|
18
|
+
[William Meleyal](https://github.com/meleyal)
|
19
|
+
[#438](https://github.com/realm/jazzy/issues/438)
|
20
|
+
|
21
|
+
* The lint report in `undocumented.json` is more human-readable: includes fully
|
22
|
+
qualified symbol names, pretty printed.
|
23
|
+
[Paul Cantrell](https://github.com/pcantrell)
|
24
|
+
[#598](https://github.com/realm/jazzy/issues/598)
|
25
|
+
|
26
|
+
* The `exclude` option now properly supports wildcards.
|
27
|
+
[Paul Cantrell](https://github.com/pcantrell)
|
28
|
+
[#640](https://github.com/realm/jazzy/issues/640)
|
29
|
+
|
1
30
|
## 0.7.0
|
2
31
|
|
3
32
|
##### Breaking
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -52,7 +52,7 @@ Swift header documentation is written in markdown and supports a number of speci
|
|
52
52
|
For a complete list and examples, see Erica Sadun's post on [*Swift header documentation in Xcode 7*](http://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/).
|
53
53
|
|
54
54
|
For Objective-C documentation the same keywords are supported, but note that the format
|
55
|
-
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/library/
|
55
|
+
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.**
|
56
56
|
|
57
57
|
### Swift
|
58
58
|
|
@@ -6,6 +6,8 @@ task :prepare do
|
|
6
6
|
Dir.chdir(fw) do
|
7
7
|
basename = File.basename(fw, '.framework')
|
8
8
|
FileUtils.rm_f(basename)
|
9
|
+
FileUtils.rm_f('Versions/Current')
|
10
|
+
FileUtils.rm_f('Resources')
|
9
11
|
|
10
12
|
File.symlink('A', 'Versions/Current')
|
11
13
|
File.symlink("Versions/Current/#{basename}", "#{basename}")
|
data/lib/jazzy/config.rb
CHANGED
@@ -151,10 +151,11 @@ module Jazzy
|
|
151
151
|
|
152
152
|
config_attr :excluded_files,
|
153
153
|
command_line: ['-e', '--exclude file1,file2,directory3,…fileN', Array],
|
154
|
-
description: 'Files/directories to be excluded from documentation'
|
154
|
+
description: 'Files/directories to be excluded from documentation. '\
|
155
|
+
'Supports wildcards.',
|
155
156
|
default: [],
|
156
157
|
parse: ->(files) do
|
157
|
-
Array(files).map { |f| expand_path(f) }
|
158
|
+
Array(files).map { |f| expand_path(f).to_s }
|
158
159
|
end
|
159
160
|
|
160
161
|
config_attr :swift_version,
|
data/lib/jazzy/doc_builder.rb
CHANGED
@@ -32,7 +32,7 @@ module Jazzy
|
|
32
32
|
def self.doc_structure_for_docs(docs)
|
33
33
|
docs.map do |doc|
|
34
34
|
children = doc.children
|
35
|
-
.sort_by { |c| [c.nav_order, c.name] }
|
35
|
+
.sort_by { |c| [c.nav_order, c.name, c.usr] }
|
36
36
|
.flat_map do |child|
|
37
37
|
# FIXME: include arbitrarily nested extensible types
|
38
38
|
[{ name: child.name, url: child.url }] +
|
@@ -161,72 +161,29 @@ module Jazzy
|
|
161
161
|
end
|
162
162
|
end
|
163
163
|
|
164
|
-
def self.
|
165
|
-
|
166
|
-
|
167
|
-
|
168
|
-
|
169
|
-
|
170
|
-
|
171
|
-
|
172
|
-
|
173
|
-
end
|
174
|
-
end
|
175
|
-
|
176
|
-
def self.filepath_for_token(token)
|
177
|
-
if ENV['JAZZY_INTEGRATION_SPECS']
|
178
|
-
Pathname.new(token['key.filepath']).basename.to_s
|
179
|
-
else
|
180
|
-
token['key.filepath']
|
181
|
-
end
|
182
|
-
end
|
183
|
-
|
184
|
-
def self.line_number_for_token(token)
|
185
|
-
if token['key.doc.line']
|
186
|
-
token['key.doc.line'] # Objective-C
|
187
|
-
else
|
188
|
-
token['key.parsed_scope.start'] # Swift
|
189
|
-
end
|
190
|
-
end
|
191
|
-
|
192
|
-
def self.warnings_for_tokens(tokens_by_file)
|
193
|
-
warnings = []
|
194
|
-
tokens_by_file.each_key do |file|
|
195
|
-
tokens_by_file[file].each do |token|
|
196
|
-
warnings << {
|
197
|
-
file: filepath_for_token(token),
|
198
|
-
line: line_number_for_token(token),
|
199
|
-
symbol: token['key.name'],
|
200
|
-
symbol_kind: token['key.kind'],
|
201
|
-
warning: 'undocumented',
|
202
|
-
}
|
203
|
-
end
|
164
|
+
def self.undocumented_warnings(decls)
|
165
|
+
decls.map do |decl|
|
166
|
+
{
|
167
|
+
file: decl.file,
|
168
|
+
line: decl.line || decl.start_line,
|
169
|
+
symbol: decl.fully_qualified_name,
|
170
|
+
symbol_kind: decl.type.kind,
|
171
|
+
warning: 'undocumented',
|
172
|
+
}
|
204
173
|
end
|
205
|
-
warnings
|
206
174
|
end
|
207
175
|
|
208
176
|
def self.write_lint_report(undocumented, options)
|
209
177
|
(options.output + 'undocumented.json').open('w') do |f|
|
210
|
-
|
211
|
-
if d['key.filepath']
|
212
|
-
Pathname.new(d['key.filepath']).basename.to_s
|
213
|
-
else
|
214
|
-
d['key.modulename'] || ''
|
215
|
-
end
|
216
|
-
end
|
217
|
-
|
218
|
-
warnings = warnings_for_tokens(tokens_by_file)
|
178
|
+
warnings = undocumented_warnings(undocumented)
|
219
179
|
|
220
180
|
lint_report = {
|
221
|
-
warnings: warnings
|
222
|
-
|
223
|
-
|
224
|
-
|
225
|
-
else
|
226
|
-
options.source_directory
|
227
|
-
end),
|
181
|
+
warnings: warnings.sort_by do |w|
|
182
|
+
[w[:file], w[:line] || 0, w[:symbol], w[:symbol_kind]]
|
183
|
+
end,
|
184
|
+
source_directory: options.source_directory,
|
228
185
|
}
|
229
|
-
f.write(lint_report
|
186
|
+
f.write(JSON.pretty_generate(lint_report))
|
230
187
|
end
|
231
188
|
end
|
232
189
|
|
data/lib/jazzy/gem_version.rb
CHANGED
@@ -5,15 +5,20 @@ module Jazzy
|
|
5
5
|
|
6
6
|
attr_reader :level
|
7
7
|
|
8
|
-
ACCESSIBILITY_PRIVATE
|
8
|
+
ACCESSIBILITY_PRIVATE = 'source.lang.swift.accessibility.private'.freeze
|
9
|
+
ACCESSIBILITY_FILEPRIVATE =
|
10
|
+
'source.lang.swift.accessibility.fileprivate'.freeze
|
9
11
|
ACCESSIBILITY_INTERNAL = 'source.lang.swift.accessibility.internal'.freeze
|
10
|
-
ACCESSIBILITY_PUBLIC
|
12
|
+
ACCESSIBILITY_PUBLIC = 'source.lang.swift.accessibility.public'.freeze
|
13
|
+
ACCESSIBILITY_OPEN = 'source.lang.swift.accessibility.open'.freeze
|
11
14
|
|
12
15
|
def initialize(accessibility)
|
13
16
|
@level = case accessibility
|
14
17
|
when ACCESSIBILITY_PRIVATE then :private
|
18
|
+
when ACCESSIBILITY_FILEPRIVATE then :fileprivate
|
15
19
|
when ACCESSIBILITY_INTERNAL then :internal
|
16
20
|
when ACCESSIBILITY_PUBLIC then :public
|
21
|
+
when ACCESSIBILITY_OPEN then :open
|
17
22
|
else
|
18
23
|
raise 'cannot initialize AccessControlLevel with ' \
|
19
24
|
"'#{accessibility}'"
|
@@ -35,7 +40,9 @@ module Jazzy
|
|
35
40
|
def self.from_explicit_declaration(declaration_string)
|
36
41
|
case declaration_string
|
37
42
|
when /private\ / then private
|
43
|
+
when /fileprivate\ / then fileprivate
|
38
44
|
when /public\ / then public
|
45
|
+
when /open\ / then open
|
39
46
|
when /internal\ / then internal
|
40
47
|
end
|
41
48
|
end
|
@@ -43,8 +50,10 @@ module Jazzy
|
|
43
50
|
def self.from_human_string(string)
|
44
51
|
case string.to_s.downcase
|
45
52
|
when 'private' then private
|
53
|
+
when 'fileprivate' then fileprivate
|
46
54
|
when 'internal' then internal
|
47
55
|
when 'public' then public
|
56
|
+
when 'open' then open
|
48
57
|
else raise "cannot initialize AccessControlLevel with '#{string}'"
|
49
58
|
end
|
50
59
|
end
|
@@ -53,6 +62,10 @@ module Jazzy
|
|
53
62
|
new(ACCESSIBILITY_PRIVATE)
|
54
63
|
end
|
55
64
|
|
65
|
+
def self.fileprivate
|
66
|
+
new(ACCESSIBILITY_FILEPRIVATE)
|
67
|
+
end
|
68
|
+
|
56
69
|
def self.internal
|
57
70
|
new(ACCESSIBILITY_INTERNAL)
|
58
71
|
end
|
@@ -61,10 +74,16 @@ module Jazzy
|
|
61
74
|
new(ACCESSIBILITY_PUBLIC)
|
62
75
|
end
|
63
76
|
|
77
|
+
def self.open
|
78
|
+
new(ACCESSIBILITY_OPEN)
|
79
|
+
end
|
80
|
+
|
64
81
|
LEVELS = {
|
65
82
|
private: 0,
|
66
|
-
|
67
|
-
|
83
|
+
fileprivate: 1,
|
84
|
+
internal: 2,
|
85
|
+
open: 3,
|
86
|
+
public: 4,
|
68
87
|
}.freeze
|
69
88
|
|
70
89
|
def <=>(other)
|
data/lib/jazzy/sourcekitten.rb
CHANGED
@@ -15,7 +15,7 @@ module Jazzy
|
|
15
15
|
# This module interacts with the sourcekitten command-line executable
|
16
16
|
module SourceKitten
|
17
17
|
@documented_count = 0
|
18
|
-
@
|
18
|
+
@undocumented_decls = []
|
19
19
|
|
20
20
|
# Group root-level docs by custom categories (if any) and type
|
21
21
|
def self.group_docs(docs)
|
@@ -150,8 +150,8 @@ module Jazzy
|
|
150
150
|
|
151
151
|
def self.make_default_doc_info(declaration)
|
152
152
|
# @todo: Fix these
|
153
|
-
declaration.line =
|
154
|
-
declaration.column =
|
153
|
+
declaration.line = nil
|
154
|
+
declaration.column = nil
|
155
155
|
declaration.abstract = 'Undocumented'
|
156
156
|
declaration.parameters = []
|
157
157
|
declaration.children = []
|
@@ -186,7 +186,7 @@ module Jazzy
|
|
186
186
|
filepath = doc['key.filepath']
|
187
187
|
objc = Config.instance.objc_mode
|
188
188
|
if filepath && (filepath.start_with?(source_directory) || objc)
|
189
|
-
@
|
189
|
+
@undocumented_decls << declaration
|
190
190
|
end
|
191
191
|
return nil if !documented_child?(doc) && @skip_undocumented
|
192
192
|
make_default_doc_info(declaration)
|
@@ -222,12 +222,11 @@ module Jazzy
|
|
222
222
|
# rubocop:disable Metrics/PerceivedComplexity
|
223
223
|
def self.make_doc_info(doc, declaration)
|
224
224
|
return unless should_document?(doc)
|
225
|
+
|
225
226
|
unless doc['key.doc.full_as_xml']
|
226
227
|
return process_undocumented_token(doc, declaration)
|
227
228
|
end
|
228
229
|
|
229
|
-
declaration.line = doc['key.doc.line']
|
230
|
-
declaration.column = doc['key.doc.column']
|
231
230
|
declaration.declaration = Highlighter.highlight(
|
232
231
|
doc['key.parsed_declaration'] || doc['key.doc.declaration'],
|
233
232
|
Config.instance.objc_mode ? 'objc' : 'swift',
|
@@ -237,6 +236,7 @@ module Jazzy
|
|
237
236
|
doc['key.swift_declaration'], 'swift'
|
238
237
|
)
|
239
238
|
end
|
239
|
+
|
240
240
|
declaration.abstract = Jazzy.markdown.render(doc['key.doc.comment'] || '')
|
241
241
|
declaration.discussion = ''
|
242
242
|
declaration.return = make_paragraphs(doc, 'key.doc.result_discussion')
|
@@ -291,11 +291,14 @@ module Jazzy
|
|
291
291
|
end
|
292
292
|
|
293
293
|
declaration.file = Pathname(doc['key.filepath']) if doc['key.filepath']
|
294
|
-
declaration.usr
|
294
|
+
declaration.usr = doc['key.usr']
|
295
|
+
declaration.modulename = doc['key.modulename']
|
295
296
|
declaration.name = doc['key.name']
|
296
297
|
declaration.mark = current_mark
|
297
298
|
declaration.access_control_level =
|
298
299
|
SourceDeclaration::AccessControlLevel.from_doc(doc)
|
300
|
+
declaration.line = doc['key.doc.line']
|
301
|
+
declaration.column = doc['key.doc.column']
|
299
302
|
declaration.start_line = doc['key.parsed_scope.start']
|
300
303
|
declaration.end_line = doc['key.parsed_scope.end']
|
301
304
|
|
@@ -310,9 +313,9 @@ module Jazzy
|
|
310
313
|
# rubocop:enable Metrics/MethodLength
|
311
314
|
|
312
315
|
def self.doc_coverage
|
313
|
-
return 0 if @documented_count == 0 && @
|
316
|
+
return 0 if @documented_count == 0 && @undocumented_decls.count == 0
|
314
317
|
(100 * @documented_count) /
|
315
|
-
(@
|
318
|
+
(@undocumented_decls.count + @documented_count)
|
316
319
|
end
|
317
320
|
|
318
321
|
# Merges multiple extensions of the same entity into a single document.
|
@@ -414,7 +417,9 @@ module Jazzy
|
|
414
417
|
excluded_files = Config.instance.excluded_files
|
415
418
|
json.map do |doc|
|
416
419
|
key = doc.keys.first
|
417
|
-
doc[key] unless excluded_files.detect
|
420
|
+
doc[key] unless excluded_files.detect do |exclude|
|
421
|
+
File.fnmatch?(exclude, key)
|
422
|
+
end
|
418
423
|
end.compact
|
419
424
|
end
|
420
425
|
|
@@ -547,7 +552,7 @@ module Jazzy
|
|
547
552
|
docs = group_docs(docs)
|
548
553
|
make_doc_urls(docs)
|
549
554
|
autolink(docs, ungrouped_docs)
|
550
|
-
[docs, doc_coverage, @
|
555
|
+
[docs, doc_coverage, @undocumented_decls]
|
551
556
|
end
|
552
557
|
end
|
553
558
|
end
|
data/spec/integration_spec.rb
CHANGED
@@ -69,6 +69,15 @@ CLIntegracon.configure do |c|
|
|
69
69
|
c.ignores %r{^(?!(docs/|execution_output.txt))}
|
70
70
|
c.ignores '*.tgz'
|
71
71
|
|
72
|
+
# Remove absolute paths from output
|
73
|
+
c.transform_produced '**/undocumented.json' do |path|
|
74
|
+
File.write(
|
75
|
+
path,
|
76
|
+
File.read(path).gsub(
|
77
|
+
(ROOT + 'tmp').to_s,
|
78
|
+
'<TMP>'))
|
79
|
+
end
|
80
|
+
|
72
81
|
# Transform produced databases to csv
|
73
82
|
c.transform_produced '**/*.dsidx' do |path|
|
74
83
|
File.open("#{path}.csv", 'w') do |file|
|
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.7.
|
4
|
+
version: 0.7.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- JP Simard
|
@@ -10,7 +10,7 @@ authors:
|
|
10
10
|
autorequire:
|
11
11
|
bindir: bin
|
12
12
|
cert_chain: []
|
13
|
-
date: 2016-
|
13
|
+
date: 2016-09-13 00:00:00.000000000 Z
|
14
14
|
dependencies:
|
15
15
|
- !ruby/object:Gem::Dependency
|
16
16
|
name: cocoapods
|