jazzy 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3bdc6c255a16e1b1494039f0761ed607e0a6dc75
-  data.tar.gz: 46315c068326227766dc54f87f292c21c76d1e78
+  metadata.gz: 407cbe5270841f8ec4c1f0bce108b166a11dbf20
+  data.tar.gz: 5e36875d2c77dae45f19aeb501b5db4ef6b9c1b7
 SHA512:
-  metadata.gz: 57a1884009cb79217841982ce9b25ddf12a1085cf8c0d8b1b8f7be456b8b18f913e11e81dc4b87adc68e606c8d8fd32c72ab223080fe06725cc2815a0b2619ca
-  data.tar.gz: 853465acf5e3be80f3c026d9782711bb8dfd25459860a19e128c6ae71912f2b897b0dc116c1f86dfd17fe3f0d2b652535895922e86e75b8a058fd81f0458c38c
+  metadata.gz: 3b39e6b6c7039637d51ab118ff1d2d53e4fff1fe2ca4106d261d75d437f0fbce26430c81b46a0a13d984566d98b1a95403243d271d08453f2e1dfdaea57f79ed
+  data.tar.gz: f76fe47dd5d5c91b556a7265e72a37cc38aa8f561282db1c9455aa981b36081ccafc839ce5b5c76b60df111ed7138ba1eaf79d9905a9c974012b179ae16af13b

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.7.1
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Added support for the new access control specifiers of fileprivate and open.  
+  [Shmuel Kallner](https://github.com/shmuelk)
+  [#645](https://github.com/realm/jazzy/issues/645)
+  [#646](https://github.com/realm/jazzy/issues/646)
+ 
+##### Bug Fixes
+
+* Fix issue where jazzy could not be installed from Gemfile due to
+  SourceKitten symlinks already being present.  
+  [William Meleyal](https://github.com/meleyal)
+  [#438](https://github.com/realm/jazzy/issues/438)
+
+* The lint report in `undocumented.json` is more human-readable: includes fully
+  qualified symbol names, pretty printed.  
+  [Paul Cantrell](https://github.com/pcantrell)
+  [#598](https://github.com/realm/jazzy/issues/598)
+
+* The `exclude` option now properly supports wildcards.  
+  [Paul Cantrell](https://github.com/pcantrell)
+  [#640](https://github.com/realm/jazzy/issues/640)
+
 ## 0.7.0
 
 ##### Breaking

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.7.0)
+    jazzy (0.7.1)
       cocoapods (~> 1.0)
       mustache (~> 0.99)
       open4

data/README.md

@@ -52,7 +52,7 @@ Swift header documentation is written in markdown and supports a number of speci
 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/).
 
 For Objective-C documentation the same keywords are supported, but note that the format
-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.**
+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.**
 
 ### Swift
 

data/lib/jazzy/SourceKitten/Rakefile

@@ -6,6 +6,8 @@ task :prepare do
     Dir.chdir(fw) do
       basename = File.basename(fw, '.framework')
       FileUtils.rm_f(basename)
+      FileUtils.rm_f('Versions/Current')
+      FileUtils.rm_f('Resources')
 
       File.symlink('A',                            'Versions/Current')
       File.symlink("Versions/Current/#{basename}", "#{basename}")

data/lib/jazzy/config.rb

@@ -151,10 +151,11 @@ module Jazzy
 
     config_attr :excluded_files,
       command_line: ['-e', '--exclude file1,file2,directory3,…fileN', Array],
-      description: 'Files/directories to be excluded from documentation',
+      description: 'Files/directories to be excluded from documentation. '\
+                   'Supports wildcards.',
       default: [],
       parse: ->(files) do
-        Array(files).map { |f| expand_path(f) }
+        Array(files).map { |f| expand_path(f).to_s }
       end
 
     config_attr :swift_version,

data/lib/jazzy/doc_builder.rb

@@ -32,7 +32,7 @@ module Jazzy
     def self.doc_structure_for_docs(docs)
       docs.map do |doc|
         children = doc.children
-                      .sort_by { |c| [c.nav_order, c.name] }
+                      .sort_by { |c| [c.nav_order, c.name, c.usr] }
                       .flat_map do |child|
           # FIXME: include arbitrarily nested extensible types
           [{ name: child.name, url: child.url }] +
@@ -161,72 +161,29 @@ module Jazzy
       end
     end
 
-    def self.decl_for_token(token)
-      if token['key.parsed_declaration']
-        token['key.parsed_declaration']
-      elsif token['key.annotated_decl']
-        token['key.annotated_decl'].gsub(/<[^>]+>/, '')
-      elsif token['key.name']
-        token['key.name']
-      else
-        'unknown declaration'
-      end
-    end
-
-    def self.filepath_for_token(token)
-      if ENV['JAZZY_INTEGRATION_SPECS']
-        Pathname.new(token['key.filepath']).basename.to_s
-      else
-        token['key.filepath']
-      end
-    end
-
-    def self.line_number_for_token(token)
-      if token['key.doc.line']
-        token['key.doc.line'] # Objective-C
-      else
-        token['key.parsed_scope.start'] # Swift
-      end
-    end
-
-    def self.warnings_for_tokens(tokens_by_file)
-      warnings = []
-      tokens_by_file.each_key do |file|
-        tokens_by_file[file].each do |token|
-          warnings << {
-            file: filepath_for_token(token),
-            line: line_number_for_token(token),
-            symbol: token['key.name'],
-            symbol_kind: token['key.kind'],
-            warning: 'undocumented',
-          }
-        end
+    def self.undocumented_warnings(decls)
+      decls.map do |decl|
+        {
+          file: decl.file,
+          line: decl.line || decl.start_line,
+          symbol: decl.fully_qualified_name,
+          symbol_kind: decl.type.kind,
+          warning: 'undocumented',
+        }
       end
-      warnings
     end
 
     def self.write_lint_report(undocumented, options)
       (options.output + 'undocumented.json').open('w') do |f|
-        tokens_by_file = undocumented.group_by do |d|
-          if d['key.filepath']
-            Pathname.new(d['key.filepath']).basename.to_s
-          else
-            d['key.modulename'] || ''
-          end
-        end
-
-        warnings = warnings_for_tokens(tokens_by_file)
+        warnings = undocumented_warnings(undocumented)
 
         lint_report = {
-          warnings: warnings,
-          source_directory: (
-            if ENV['JAZZY_INTEGRATION_SPECS']
-              'Specs'
-            else
-              options.source_directory
-            end),
+          warnings: warnings.sort_by do |w|
+            [w[:file], w[:line] || 0, w[:symbol], w[:symbol_kind]]
+          end,
+          source_directory: options.source_directory,
         }
-        f.write(lint_report.to_json)
+        f.write(JSON.pretty_generate(lint_report))
       end
     end
 

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.7.0'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.7.1'.freeze unless defined? Jazzy::VERSION
 end

data/lib/jazzy/source_declaration.rb

@@ -60,6 +60,7 @@ module Jazzy
     attr_accessor :line
     attr_accessor :column
     attr_accessor :usr
+    attr_accessor :modulename
     attr_accessor :name
     attr_accessor :declaration
     attr_accessor :other_language_declaration

data/lib/jazzy/source_declaration/access_control_level.rb

@@ -5,15 +5,20 @@ module Jazzy
 
       attr_reader :level
 
-      ACCESSIBILITY_PRIVATE  = 'source.lang.swift.accessibility.private'.freeze
+      ACCESSIBILITY_PRIVATE = 'source.lang.swift.accessibility.private'.freeze
+      ACCESSIBILITY_FILEPRIVATE =
+        'source.lang.swift.accessibility.fileprivate'.freeze
       ACCESSIBILITY_INTERNAL = 'source.lang.swift.accessibility.internal'.freeze
-      ACCESSIBILITY_PUBLIC   = 'source.lang.swift.accessibility.public'.freeze
+      ACCESSIBILITY_PUBLIC = 'source.lang.swift.accessibility.public'.freeze
+      ACCESSIBILITY_OPEN = 'source.lang.swift.accessibility.open'.freeze
 
       def initialize(accessibility)
         @level = case accessibility
                  when ACCESSIBILITY_PRIVATE then :private
+                 when ACCESSIBILITY_FILEPRIVATE then :fileprivate
                  when ACCESSIBILITY_INTERNAL then :internal
                  when ACCESSIBILITY_PUBLIC then :public
+                 when ACCESSIBILITY_OPEN then :open
                  else
                    raise 'cannot initialize AccessControlLevel with ' \
                      "'#{accessibility}'"
@@ -35,7 +40,9 @@ module Jazzy
       def self.from_explicit_declaration(declaration_string)
         case declaration_string
         when /private\ / then private
+        when /fileprivate\ / then fileprivate
         when /public\ / then public
+        when /open\ / then open
         when /internal\ / then internal
         end
       end
@@ -43,8 +50,10 @@ module Jazzy
       def self.from_human_string(string)
         case string.to_s.downcase
         when 'private' then private
+        when 'fileprivate' then fileprivate
         when 'internal' then internal
         when 'public' then public
+        when 'open' then open
         else raise "cannot initialize AccessControlLevel with '#{string}'"
         end
       end
@@ -53,6 +62,10 @@ module Jazzy
         new(ACCESSIBILITY_PRIVATE)
       end
 
+      def self.fileprivate
+        new(ACCESSIBILITY_FILEPRIVATE)
+      end
+
       def self.internal
         new(ACCESSIBILITY_INTERNAL)
       end
@@ -61,10 +74,16 @@ module Jazzy
         new(ACCESSIBILITY_PUBLIC)
       end
 
+      def self.open
+        new(ACCESSIBILITY_OPEN)
+      end
+
       LEVELS = {
         private: 0,
-        internal: 1,
-        public: 2,
+        fileprivate: 1,
+        internal: 2,
+        open: 3,
+        public: 4,
       }.freeze
 
       def <=>(other)

data/lib/jazzy/sourcekitten.rb

@@ -15,7 +15,7 @@ module Jazzy
   # This module interacts with the sourcekitten command-line executable
   module SourceKitten
     @documented_count = 0
-    @undocumented_tokens = []
+    @undocumented_decls = []
 
     # Group root-level docs by custom categories (if any) and type
     def self.group_docs(docs)
@@ -150,8 +150,8 @@ module Jazzy
 
     def self.make_default_doc_info(declaration)
       # @todo: Fix these
-      declaration.line = 0
-      declaration.column = 0
+      declaration.line = nil
+      declaration.column = nil
       declaration.abstract = 'Undocumented'
       declaration.parameters = []
       declaration.children = []
@@ -186,7 +186,7 @@ module Jazzy
       filepath = doc['key.filepath']
       objc = Config.instance.objc_mode
       if filepath && (filepath.start_with?(source_directory) || objc)
-        @undocumented_tokens << doc
+        @undocumented_decls << declaration
       end
       return nil if !documented_child?(doc) && @skip_undocumented
       make_default_doc_info(declaration)
@@ -222,12 +222,11 @@ module Jazzy
     # rubocop:disable Metrics/PerceivedComplexity
     def self.make_doc_info(doc, declaration)
       return unless should_document?(doc)
+
       unless doc['key.doc.full_as_xml']
         return process_undocumented_token(doc, declaration)
       end
 
-      declaration.line = doc['key.doc.line']
-      declaration.column = doc['key.doc.column']
       declaration.declaration = Highlighter.highlight(
         doc['key.parsed_declaration'] || doc['key.doc.declaration'],
         Config.instance.objc_mode ? 'objc' : 'swift',
@@ -237,6 +236,7 @@ module Jazzy
           doc['key.swift_declaration'], 'swift'
         )
       end
+
       declaration.abstract = Jazzy.markdown.render(doc['key.doc.comment'] || '')
       declaration.discussion = ''
       declaration.return = make_paragraphs(doc, 'key.doc.result_discussion')
@@ -291,11 +291,14 @@ module Jazzy
         end
 
         declaration.file = Pathname(doc['key.filepath']) if doc['key.filepath']
-        declaration.usr  = doc['key.usr']
+        declaration.usr = doc['key.usr']
+        declaration.modulename = doc['key.modulename']
         declaration.name = doc['key.name']
         declaration.mark = current_mark
         declaration.access_control_level =
           SourceDeclaration::AccessControlLevel.from_doc(doc)
+        declaration.line = doc['key.doc.line']
+        declaration.column = doc['key.doc.column']
         declaration.start_line = doc['key.parsed_scope.start']
         declaration.end_line = doc['key.parsed_scope.end']
 
@@ -310,9 +313,9 @@ module Jazzy
     # rubocop:enable Metrics/MethodLength
 
     def self.doc_coverage
-      return 0 if @documented_count == 0 && @undocumented_tokens.count == 0
+      return 0 if @documented_count == 0 && @undocumented_decls.count == 0
       (100 * @documented_count) /
-        (@undocumented_tokens.count + @documented_count)
+        (@undocumented_decls.count + @documented_count)
     end
 
     # Merges multiple extensions of the same entity into a single document.
@@ -414,7 +417,9 @@ module Jazzy
       excluded_files = Config.instance.excluded_files
       json.map do |doc|
         key = doc.keys.first
-        doc[key] unless excluded_files.detect { |f| File.fnmatch?(key, f) }
+        doc[key] unless excluded_files.detect do |exclude|
+          File.fnmatch?(exclude, key)
+        end
       end.compact
     end
 
@@ -547,7 +552,7 @@ module Jazzy
       docs = group_docs(docs)
       make_doc_urls(docs)
       autolink(docs, ungrouped_docs)
-      [docs, doc_coverage, @undocumented_tokens]
+      [docs, doc_coverage, @undocumented_decls]
     end
   end
 end

data/spec/integration_spec.rb

@@ -69,6 +69,15 @@ CLIntegracon.configure do |c|
   c.ignores %r{^(?!(docs/|execution_output.txt))}
   c.ignores '*.tgz'
 
+  # Remove absolute paths from output
+  c.transform_produced '**/undocumented.json' do |path|
+    File.write(
+      path,
+      File.read(path).gsub(
+        (ROOT + 'tmp').to_s,
+        '<TMP>'))
+  end
+
   # Transform produced databases to csv
   c.transform_produced '**/*.dsidx' do |path|
     File.open("#{path}.csv", 'w') do |file|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazzy
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - JP Simard
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-12 00:00:00.000000000 Z
+date: 2016-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocoapods