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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 3bdc6c255a16e1b1494039f0761ed607e0a6dc75
4
- data.tar.gz: 46315c068326227766dc54f87f292c21c76d1e78
3
+ metadata.gz: 407cbe5270841f8ec4c1f0bce108b166a11dbf20
4
+ data.tar.gz: 5e36875d2c77dae45f19aeb501b5db4ef6b9c1b7
5
5
  SHA512:
6
- metadata.gz: 57a1884009cb79217841982ce9b25ddf12a1085cf8c0d8b1b8f7be456b8b18f913e11e81dc4b87adc68e606c8d8fd32c72ab223080fe06725cc2815a0b2619ca
7
- data.tar.gz: 853465acf5e3be80f3c026d9782711bb8dfd25459860a19e128c6ae71912f2b897b0dc116c1f86dfd17fe3f0d2b652535895922e86e75b8a058fd81f0458c38c
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
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- jazzy (0.7.0)
4
+ jazzy (0.7.1)
5
5
  cocoapods (~> 1.0)
6
6
  mustache (~> 0.99)
7
7
  open4
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/mac/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html) for more details. **Note: `jazzy` currently does not support _all_ Objective-C keywords listed in this document.**
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,
@@ -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.decl_for_token(token)
165
- if token['key.parsed_declaration']
166
- token['key.parsed_declaration']
167
- elsif token['key.annotated_decl']
168
- token['key.annotated_decl'].gsub(/<[^>]+>/, '')
169
- elsif token['key.name']
170
- token['key.name']
171
- else
172
- 'unknown declaration'
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
- tokens_by_file = undocumented.group_by do |d|
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
- source_directory: (
223
- if ENV['JAZZY_INTEGRATION_SPECS']
224
- 'Specs'
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.to_json)
186
+ f.write(JSON.pretty_generate(lint_report))
230
187
  end
231
188
  end
232
189
 
@@ -1,3 +1,3 @@
1
1
  module Jazzy
2
- VERSION = '0.7.0'.freeze unless defined? Jazzy::VERSION
2
+ VERSION = '0.7.1'.freeze unless defined? Jazzy::VERSION
3
3
  end
@@ -60,6 +60,7 @@ module Jazzy
60
60
  attr_accessor :line
61
61
  attr_accessor :column
62
62
  attr_accessor :usr
63
+ attr_accessor :modulename
63
64
  attr_accessor :name
64
65
  attr_accessor :declaration
65
66
  attr_accessor :other_language_declaration
@@ -5,15 +5,20 @@ module Jazzy
5
5
 
6
6
  attr_reader :level
7
7
 
8
- ACCESSIBILITY_PRIVATE = 'source.lang.swift.accessibility.private'.freeze
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 = 'source.lang.swift.accessibility.public'.freeze
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
- internal: 1,
67
- public: 2,
83
+ fileprivate: 1,
84
+ internal: 2,
85
+ open: 3,
86
+ public: 4,
68
87
  }.freeze
69
88
 
70
89
  def <=>(other)
@@ -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
- @undocumented_tokens = []
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 = 0
154
- declaration.column = 0
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
- @undocumented_tokens << doc
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 = doc['key.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 && @undocumented_tokens.count == 0
316
+ return 0 if @documented_count == 0 && @undocumented_decls.count == 0
314
317
  (100 * @documented_count) /
315
- (@undocumented_tokens.count + @documented_count)
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 { |f| File.fnmatch?(key, f) }
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, @undocumented_tokens]
555
+ [docs, doc_coverage, @undocumented_decls]
551
556
  end
552
557
  end
553
558
  end
@@ -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.0
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-06-12 00:00:00.000000000 Z
13
+ date: 2016-09-13 00:00:00.000000000 Z
14
14
  dependencies:
15
15
  - !ruby/object:Gem::Dependency
16
16
  name: cocoapods