jazzy 0.5.0 → 0.6.0

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>15C50</string>
+	<string>15E65</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.7.3</string>
+	<string>0.12.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleSupportedPlatforms</key>
@@ -29,17 +29,17 @@
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>7C68</string>
+	<string>7D175</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>15C43</string>
+	<string>15E60</string>
 	<key>DTSDKName</key>
 	<string>macosx10.11</string>
 	<key>DTXcode</key>
-	<string>0720</string>
+	<string>0730</string>
 	<key>DTXcodeBuild</key>
-	<string>7C68</string>
+	<string>7D175</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2015 SourceKitten. All rights reserved.</string>
 </dict>

data/lib/jazzy/config.rb

@@ -11,15 +11,17 @@ module Jazzy
   class Config
     # rubocop:disable Style/AccessorMethodName
     class Attribute
-      attr_reader :name, :description, :command_line, :default, :parse
+      attr_reader :name, :description, :command_line, :config_file_key,
+                  :default, :parse
 
       def initialize(name, description: nil, command_line: nil,
                      default: nil, parse: ->(x) { x })
-        @name = name
+        @name = name.to_s
         @description = Array(description)
         @command_line = Array(command_line)
         @default = default
         @parse = parse
+        @config_file_key = full_command_line_name || @name
       end
 
       def get(config)
@@ -53,6 +55,21 @@ module Jazzy
           set(config, val)
         end
       end
+
+      private
+
+      def full_command_line_name
+        long_option_names = command_line.map do |opt|
+          Regexp.last_match(1) if opt =~ %r{
+            ^--           # starts with double dash
+            (?:\[no-\])?  # optional prefix for booleans
+            ([^\s]+)      # long option name
+          }x
+        end
+        if long_option_name = long_option_names.compact.first
+          long_option_name.tr('-', '_')
+        end
+      end
     end
     # rubocop:enable Style/AccessorMethodName
 
@@ -142,7 +159,7 @@ module Jazzy
 
     config_attr :swift_version,
       command_line: '--swift-version VERSION',
-      default: '2.1.1',
+      default: '2.2',
       parse: ->(v) do
         raise 'jazzy only supports Swift 2.0 or later.' if v.to_f < 2
         v
@@ -221,6 +238,11 @@ module Jazzy
 
     # ──────── Doc generation options ────────
 
+    config_attr :skip_documentation,
+      command_line: '--skip-documentation',
+      description: 'Will skip the documentation generation phase.',
+      default: false
+
     config_attr :min_acl,
       command_line: '--min-acl [private | internal | public]',
       description: 'minimum access control level to document',
@@ -237,7 +259,7 @@ module Jazzy
 
     config_attr :hide_documentation_coverage,
       command_line: '--[no-]hide-documentation-coverage',
-      description: "Hide \"(X\% documented)\" from the generated documents",
+      description: 'Hide "(X% documented)" from the generated documents',
       default: false
 
     config_attr :custom_categories,
@@ -346,11 +368,24 @@ module Jazzy
 
       puts "Using config file #{config_path}"
       config_file = read_config_file(config_path)
-      self.class.all_config_attrs.each do |attr|
-        key = attr.name.to_s
-        if config_file.key?(key)
-          attr.set_if_unconfigured(self, config_file[key])
+
+      attrs_by_conf_key, attrs_by_name = %i(config_file_key name).map do |prop|
+        self.class.all_config_attrs.group_by(&prop)
+      end
+
+      config_file.each do |key, value|
+        unless attr = attrs_by_conf_key[key]
+          message = "WARNING: Unknown config file attribute #{key.inspect}"
+          if matching_name = attrs_by_name[key]
+            message << ' (Did you mean '
+            message << matching_name.first.config_file_key.inspect
+            message << '?)'
+          end
+          warn message
+          next
         end
+
+        attr.first.set_if_unconfigured(self, value)
       end
 
       self.base_path = nil
@@ -404,7 +439,7 @@ module Jazzy
           puts
           puts attr.name.to_s.tr('_', ' ').upcase
           puts
-          puts "  Config file:   #{attr.name}"
+          puts "  Config file:   #{attr.config_file_key}"
           cmd_line_forms = attr.command_line.select { |opt| opt.is_a?(String) }
           if cmd_line_forms.any?
             puts "  Command line:  #{cmd_line_forms.join(', ')}"

data/lib/jazzy/doc_builder.rb

@@ -30,9 +30,8 @@ module Jazzy
     def self.doc_structure_for_docs(docs)
       docs.map do |doc|
         children = doc.children
-                   .sort_by(&:name)
-                   .sort_by(&:nav_order)
-                   .map do |child|
+                      .sort_by { |c| [c.nav_order, c.name] }
+                      .map do |child|
           { name: child.name, url: child.url }
         end
         {
@@ -64,7 +63,7 @@ module Jazzy
           exit $?.exitstatus || 1
         end
       end
-      warn 'building site'
+
       build_docs_for_sourcekitten_output(stdout, options)
     end
 
@@ -99,19 +98,8 @@ module Jazzy
       end
     end
 
-    # Build docs given sourcekitten output
-    # @param [String] sourcekitten_output Output of sourcekitten command
-    # @param [Config] options Build options
-    # @return [SourceModule] the documented source module
-    def self.build_docs_for_sourcekitten_output(sourcekitten_output, options)
-      output_dir = options.output
-      prepare_output_dir(output_dir, options.clean)
-
-      (docs, coverage, undocumented) = SourceKitten.parse(
-        sourcekitten_output,
-        options.min_acl,
-        options.skip_undocumented,
-      )
+    def self.build_site(docs, coverage, options)
+      warn 'building site'
 
       structure = doc_structure_for_docs(docs)
 
@@ -121,9 +109,9 @@ module Jazzy
       end
 
       source_module = SourceModule.new(options, docs, structure, coverage)
-      build_docs(output_dir, source_module.docs, source_module)
 
-      write_undocumented_file(undocumented, output_dir)
+      output_dir = options.output
+      build_docs(output_dir, source_module.docs, source_module)
 
       copy_assets(output_dir)
 
@@ -135,6 +123,25 @@ module Jazzy
       source_module
     end
 
+    # Build docs given sourcekitten output
+    # @param [String] sourcekitten_output Output of sourcekitten command
+    # @param [Config] options Build options
+    # @return [SourceModule] the documented source module
+    def self.build_docs_for_sourcekitten_output(sourcekitten_output, options)
+      (docs, coverage, undocumented) = SourceKitten.parse(
+        sourcekitten_output,
+        options.min_acl,
+        options.skip_undocumented,
+      )
+
+      prepare_output_dir(options.output, options.clean)
+      write_lint_report(undocumented, options)
+
+      unless options.skip_documentation
+        build_site(docs, coverage, options)
+      end
+    end
+
     def self.relative_path_if_inside(path, base_path)
       relative = path.relative_path_from(base_path)
       if relative.to_path =~ %r{/^..(\/|$)/}
@@ -156,8 +163,40 @@ module Jazzy
       end
     end
 
-    def self.write_undocumented_file(undocumented, output_dir)
-      (output_dir + 'undocumented.txt').open('w') do |f|
+    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
+      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
@@ -165,12 +204,19 @@ module Jazzy
             d['key.modulename'] || ''
           end
         end
-        tokens_by_file.each_key do |file|
-          f.write(file + "\n")
-          tokens_by_file[file].each do |token|
-            f.write("\t" + decl_for_token(token) + "\n")
-          end
-        end
+
+        warnings = warnings_for_tokens(tokens_by_file)
+
+        lint_report = {
+          warnings: warnings,
+          source_directory: (
+            if ENV['JAZZY_INTEGRATION_SPECS']
+              'Specs'
+            else
+              options.source_directory
+            end),
+        }
+        f.write(lint_report.to_json)
       end
     end
 
@@ -221,11 +267,11 @@ module Jazzy
     def self.gh_token_url(item, source_module)
       return unless github_prefix = source_module.github_file_prefix
       return unless should_link_to_github(item.file)
-      if item.start_line && (item.start_line != item.end_line)
-        gh_line = "#L#{item.start_line}-L#{item.end_line}"
-      else
-        gh_line = "#L#{item.line}"
-      end
+      gh_line = if item.start_line && (item.start_line != item.end_line)
+                  "#L#{item.start_line}-L#{item.end_line}"
+                else
+                  "#L#{item.line}"
+                end
       relative_file_path = item.file.realpath.relative_path_from(
         source_module.root_path)
       "#{github_prefix}/#{relative_file_path}#{gh_line}"
@@ -278,10 +324,10 @@ module Jazzy
       marks.map do |mark|
         mark_children = children.select { |child| child.mark == mark }
         items = mark_children.map { |child| render_item(child, source_module) }
-        uid = "#{mark.name || 'Unnamed'}"
+        uid = (mark.name || 'Unnamed').to_s
         if mark_names_counts.key?(uid)
           mark_names_counts[uid] += 1
-          uid += "#{mark_names_counts[uid]}"
+          uid += (mark_names_counts[uid]).to_s
         else
           mark_names_counts[uid] = 1
         end

data/lib/jazzy/gem_version.rb

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

data/lib/jazzy/jazzy_markdown.rb

@@ -9,9 +9,9 @@ module Jazzy
 
     def header(text, header_level)
       text_slug = text.gsub(/[^a-zA-Z0-9]+/, '_')
-                  .downcase
-                  .sub(/^_/, '')
-                  .sub(/_$/, '')
+                      .downcase
+                      .sub(/^_/, '')
+                      .sub(/_$/, '')
 
       "<a href='##{text_slug}' class='anchor' aria-hidden=true>" \
         '<span class="header-anchor"></span>' \
@@ -44,7 +44,6 @@ module Jazzy
                             Version
                             Warning).freeze
 
-    # rubocop:disable RegexpLiteral
     SPECIAL_LIST_TYPE_REGEX = %r{
       \A\s* # optional leading spaces
       (<p>\s*)? # optional opening p tag
@@ -52,7 +51,6 @@ module Jazzy
       (#{SPECIAL_LIST_TYPES.map(&Regexp.method(:escape)).join('|')})
       [\s:] # followed by either a space or a colon
     }ix
-    # rubocop:enable RegexpLiteral
 
     ELIDED_LI_TOKEN = '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'.freeze
 

data/lib/jazzy/podspec_documenter.rb

@@ -16,7 +16,7 @@ module Jazzy
       stdout = Dir.chdir(sandbox.root) do
         pod_targets.map do |t|
           SourceKitten.run_sourcekitten(
-            %W(doc --module-name #{podspec.module_name} -target #{t})
+            %W(doc --module-name #{podspec.module_name} -- -target #{t}),
           )
         end
       end
@@ -62,15 +62,13 @@ module Jazzy
     def self.author_name(podspec)
       if podspec.authors.respond_to? :to_hash
         podspec.authors.keys.to_sentence || ''
-      else
-        if podspec.authors.respond_to? :to_ary
-          podspec.authors.to_sentence
-        else
-          podspec.authors
-        end
-      end || ''
+      elsif podspec.authors.respond_to? :to_ary
+        podspec.authors.to_sentence
+      end || podspec.authors || ''
     end
 
+    private_class_method :author_name
+
     def self.github_file_prefix(podspec)
       return unless podspec.source[:url] =~ %r{github.com[:/]+(.+)/(.+)}
       org, repo = Regexp.last_match
@@ -80,6 +78,8 @@ module Jazzy
       "https://github.com/#{org}/#{repo}/blob/#{rev}"
     end
 
+    private_class_method :github_file_prefix
+
     # @!group SourceKitten output helper methods
 
     attr_reader :pod_targets

data/lib/jazzy/source_declaration.rb

@@ -41,6 +41,13 @@ module Jazzy
       namespace_path.map(&:name).join('.')
     end
 
+    # If this declaration is an objc category, returns an array with the name
+    # of the extended objc class and the category name itself, i.e.
+    # ["NSString", "MyMethods"], nil otherwise.
+    def objc_category_name
+      name.split(/[\(\)]/) if type.objc_category?
+    end
+
     attr_accessor :file
     attr_accessor :line
     attr_accessor :column

data/lib/jazzy/source_declaration/access_control_level.rb

@@ -5,9 +5,9 @@ module Jazzy
 
       attr_reader :level
 
-      ACCESSIBILITY_PRIVATE  = 'source.lang.swift.accessibility.private'
-      ACCESSIBILITY_INTERNAL = 'source.lang.swift.accessibility.internal'
-      ACCESSIBILITY_PUBLIC   = 'source.lang.swift.accessibility.public'
+      ACCESSIBILITY_PRIVATE  = 'source.lang.swift.accessibility.private'.freeze
+      ACCESSIBILITY_INTERNAL = 'source.lang.swift.accessibility.internal'.freeze
+      ACCESSIBILITY_PUBLIC   = 'source.lang.swift.accessibility.public'.freeze
 
       def initialize(accessibility)
         @level = case accessibility

data/lib/jazzy/source_declaration/type.rb

@@ -40,6 +40,14 @@ module Jazzy
         kind == 'sourcekitten.source.lang.objc.decl.typedef'
       end
 
+      def objc_category?
+        kind == 'sourcekitten.source.lang.objc.decl.category'
+      end
+
+      def objc_class?
+        kind == 'sourcekitten.source.lang.objc.decl.class'
+      end
+
       def swift_enum_case?
         kind == 'source.lang.swift.decl.enumcase'
       end
@@ -53,8 +61,12 @@ module Jazzy
       end
 
       def declaration?
-        kind.start_with?('source.lang.swift.decl') ||
-          kind.start_with?('sourcekitten.source.lang.objc.decl')
+        kind.start_with?('source.lang.swift.decl',
+                         'sourcekitten.source.lang.objc.decl')
+      end
+
+      def extension?
+        swift_extension? || objc_category?
       end
 
       def swift_extension?
@@ -84,7 +96,7 @@ module Jazzy
         kind.hash
       end
 
-      alias_method :equals, :==
+      alias equals ==
       def ==(other)
         other && kind == other.kind
       end
@@ -156,6 +168,10 @@ module Jazzy
           jazzy: 'Ivar',
           dash: 'Ivar',
         }.freeze,
+        'sourcekitten.source.lang.objc.module.import' => {
+          jazzy: 'Module',
+          dash: 'Module',
+        }.freeze,
 
         # Swift
         'source.lang.swift.decl.function.accessor.address' => {
@@ -186,6 +202,18 @@ module Jazzy
           jazzy: 'Operator',
           dash: 'Function',
         }.freeze,
+        'source.lang.swift.decl.function.operator.infix' => {
+          jazzy: 'Infix Operator',
+          dash: 'Function',
+        }.freeze,
+        'source.lang.swift.decl.function.operator.postfix' => {
+          jazzy: 'Postfix Operator',
+          dash: 'Function',
+        }.freeze,
+        'source.lang.swift.decl.function.operator.prefix' => {
+          jazzy: 'Prefix Operator',
+          dash: 'Function',
+        }.freeze,
         'source.lang.swift.decl.function.method.class' => {
           jazzy: 'Class Method',
           dash: 'Method',
@@ -290,6 +318,10 @@ module Jazzy
           jazzy: 'Generic Type Parameter',
           dash: 'Parameter',
         }.freeze,
+        'source.lang.swift.decl.associatedtype' => {
+          jazzy: 'Associated Type',
+          dash: 'Alias',
+        }.freeze,
       }.freeze
     end
     # rubocop:enable Metrics/ClassLength