jazzy 0.13.7 → 0.14.2

data/lib/jazzy/podspec_documenter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'tmpdir'
 require 'json'
 
@@ -22,8 +24,8 @@ module Jazzy
         installer.install!
         stdout = Dir.chdir(sandbox.root) do
           targets = installer.pod_targets
-                             .select { |pt| pt.pod_name == podspec.root.name }
-                             .map(&:label)
+            .select { |pt| pt.pod_name == podspec.root.name }
+            .map(&:label)
 
           targets.map do |t|
             args = %W[doc --module-name #{podspec.module_name} -- -target #{t}]
@@ -42,8 +44,6 @@ module Jazzy
       end
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
-    # rubocop:disable Metrics/PerceivedComplexity
     # rubocop:disable Metrics/MethodLength
     def self.apply_config_defaults(podspec, config)
       return unless podspec
@@ -64,9 +64,9 @@ module Jazzy
         config.version = podspec.version.to_s
         config.version_configured = true
       end
-      unless config.github_file_prefix_configured
-        config.github_file_prefix = github_file_prefix(podspec)
-        config.github_file_prefix_configured = true
+      unless config.source_host_files_url_configured
+        config.source_host_files_url = github_file_prefix(podspec)
+        config.source_host_files_url_configured = true
       end
       unless config.swift_version_configured
         trunk_swift_build = podspec.attributes_hash['pushed_with_swift_version']
@@ -74,8 +74,6 @@ module Jazzy
         config.swift_version_configured = true
       end
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
-    # rubocop:enable Metrics/PerceivedComplexity
     # rubocop:enable Metrics/MethodLength
 
     private
@@ -94,17 +92,17 @@ module Jazzy
 
     def self.github_file_prefix(podspec)
       return unless podspec.source[:url] =~ %r{github.com[:/]+(.+)/(.+)}
+
       org, repo = Regexp.last_match
-      return unless org && repo
-      repo.sub!(/\.git$/, '')
       return unless rev = podspec.source[:tag] || podspec.source[:commit]
-      "https://github.com/#{org}/#{repo}/blob/#{rev}"
+
+      "https://github.com/#{org}/#{repo.sub(/\.git$/, '')}/blob/#{rev}"
     end
 
     private_class_method :github_file_prefix
 
     # Latest valid value for SWIFT_VERSION.
-    LATEST_SWIFT_VERSION = '5'.freeze
+    LATEST_SWIFT_VERSION = '5'
 
     # All valid values for SWIFT_VERSION that are longer
     # than a major version number.  Ordered ascending.
@@ -162,9 +160,8 @@ module Jazzy
             # Travis builds take too long when building docs for all available
             # platforms for the Moya integration spec, so we just document OSX.
             # TODO: remove once jazzy is fast enough.
-            if ENV['JAZZY_INTEGRATION_SPECS']
-              next if p.name != :osx
-            end
+            next if ENV['JAZZY_INTEGRATION_SPECS'] && p.name != :osx
+
             target("Jazzy-#{ss.name.gsub('/', '__')}-#{p.name}") do
               use_frameworks!
               platform p.name, p.deployment_target
@@ -177,4 +174,5 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/jazzy/search_builder.rb

@@ -1,21 +1,20 @@
+# frozen_string_literal: true
+
 module Jazzy
   module SearchBuilder
     def self.build(source_module, output_dir)
       decls = source_module.all_declarations.select do |d|
         d.type && d.name && !d.name.empty?
       end
-      index = Hash[decls.map do |d|
+      index = decls.to_h do |d|
         [d.url,
          {
            name: d.name,
            abstract: d.abstract && d.abstract.split(/\n/).map(&:strip).first,
-           parent_name: d.parent_in_code && d.parent_in_code.name,
+           parent_name: d.parent_in_code&.name,
          }.reject { |_, v| v.nil? || v.empty? }]
       end
-      ]
-      File.open(File.join(output_dir, 'search.json'), 'w') do |f|
-        f.write(index.to_json)
-      end
+      File.write(File.join(output_dir, 'search.json'), index.to_json)
     end
   end
 end

data/lib/jazzy/source_declaration/access_control_level.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jazzy
   class SourceDeclaration
     class AccessControlLevel
@@ -5,12 +7,12 @@ module Jazzy
 
       attr_reader :level
 
-      ACCESSIBILITY_PRIVATE = 'source.lang.swift.accessibility.private'.freeze
+      ACCESSIBILITY_PRIVATE = 'source.lang.swift.accessibility.private'
       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_OPEN = 'source.lang.swift.accessibility.open'.freeze
+        'source.lang.swift.accessibility.fileprivate'
+      ACCESSIBILITY_INTERNAL = 'source.lang.swift.accessibility.internal'
+      ACCESSIBILITY_PUBLIC = 'source.lang.swift.accessibility.public'
+      ACCESSIBILITY_OPEN = 'source.lang.swift.accessibility.open'
 
       def initialize(accessibility)
         @level = case accessibility

data/lib/jazzy/source_declaration/type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/inflector'
 
 module Jazzy
@@ -10,11 +12,24 @@ module Jazzy
 
       attr_reader :kind
 
-      def initialize(kind)
+      def initialize(kind, declaration = nil)
+        kind = fixup_kind(kind, declaration) if declaration
         @kind = kind
         @type = TYPES[kind]
       end
 
+      # Improve kind from full declaration
+      def fixup_kind(kind, declaration)
+        if kind == 'source.lang.swift.decl.class' &&
+           declaration.include?(
+             '<syntaxtype.keyword>actor</syntaxtype.keyword>',
+           )
+          'source.lang.swift.decl.actor'
+        else
+          kind
+        end
+      end
+
       def dash_type
         @type && @type[:dash]
       end
@@ -113,7 +128,8 @@ module Jazzy
       end
 
       def swift_extensible?
-        kind =~ /^source\.lang\.swift\.decl\.(class|struct|protocol|enum)$/
+        kind =~
+          /^source\.lang\.swift\.decl\.(class|struct|protocol|enum|actor)$/
       end
 
       def swift_protocol?
@@ -151,7 +167,7 @@ module Jazzy
         Type.new('Overview')
       end
 
-      MARKDOWN_KIND = 'document.markdown'.freeze
+      MARKDOWN_KIND = 'document.markdown'
 
       def self.markdown
         Type.new(MARKDOWN_KIND)
@@ -253,6 +269,11 @@ module Jazzy
           dash: 'Struct',
           global: true,
         }.freeze,
+        'sourcekitten.source.lang.objc.decl.union' => {
+          jazzy: 'Union',
+          dash: 'Union',
+          global: true,
+        }.freeze,
         'sourcekitten.source.lang.objc.decl.field' => {
           jazzy: 'Field',
           dash: 'Field',
@@ -267,6 +288,11 @@ module Jazzy
         }.freeze,
 
         # Swift
+        'source.lang.swift.decl.actor' => {
+          jazzy: 'Actor',
+          dash: 'Actor',
+          global: true,
+        }.freeze,
         'source.lang.swift.decl.function.accessor.address' => {
           jazzy: 'Addressor',
           dash: 'Function',

data/lib/jazzy/source_declaration.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 require 'jazzy/source_declaration/access_control_level'
 require 'jazzy/source_declaration/type'
 
-# rubocop:disable Metrics/ClassLength
 module Jazzy
+  # rubocop:disable Metrics/ClassLength
   class SourceDeclaration
     # kind of declaration (e.g. class, variable, function)
     attr_accessor :type
@@ -39,7 +41,7 @@ module Jazzy
     attr_accessor :parent_in_docs
 
     # counterpart of parent_in_docs
-    attr_accessor :children
+    attr_reader :children
 
     def children=(new_children)
       # Freeze to ensure that parent_in_docs stays in sync
@@ -76,7 +78,7 @@ module Jazzy
     # 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?
+      name.split(/[()]/) if type.objc_category?
     end
 
     def swift_objc_extension?
@@ -136,6 +138,7 @@ module Jazzy
     attr_accessor :unavailable_message
     attr_accessor :generic_requirements
     attr_accessor :inherited_types
+    attr_accessor :async
 
     def usage_discouraged?
       unavailable || deprecated
@@ -151,6 +154,7 @@ module Jazzy
       # Workaround functions sharing names with
       # different argument types (f(a:Int) vs. f(a:String))
       return result unless type.swift_global_function?
+
       result + "_#{type_usr}"
     end
 
@@ -175,13 +179,24 @@ module Jazzy
     # Is there at least one inherited type that is not in the given list?
     def other_inherited_types?(unwanted)
       return false unless inherited_types?
+
       inherited_types.any? { |t| !unwanted.include?(t) }
     end
 
-    # SourceKit only sets modulename for imported modules
+    # Pre-Swift 5.6: SourceKit only sets modulename for imported modules
+    # Swift 5.6+: modulename is always set
     def type_from_doc_module?
       !type.extension? ||
-        (swift? && usr && modulename.nil?)
+        (swift? && usr &&
+          (modulename.nil? || modulename == Config.instance.module_name))
+    end
+
+    # Info text for contents page by collapsed item name
+    def declaration_note
+      notes = [default_impl_abstract ? 'default implementation' : nil,
+               from_protocol_extension ? 'extension method' : nil,
+               async ? 'asynchronous' : nil].compact
+      notes.join(', ').humanize unless notes.empty?
     end
 
     def alternative_abstract
@@ -201,7 +216,9 @@ module Jazzy
       return [] unless
         Config.instance.abstract_glob_configured &&
         Config.instance.abstract_glob
+
       Config.instance.abstract_glob.select { |e| File.file? e }
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/jazzy/source_document.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'pathname'
 
 require 'jazzy/jazzy_markdown'
@@ -43,6 +45,7 @@ module Jazzy
 
     def content(source_module)
       return readme_content(source_module) if name == 'index'
+
       overview
     end
 
@@ -51,7 +54,7 @@ module Jazzy
     end
 
     def config_readme
-      readme_path.read if readme_path && readme_path.exist?
+      readme_path.read if readme_path&.exist?
     end
 
     def fallback_readme
@@ -67,7 +70,7 @@ module Jazzy
         ### License
 
         # <a href="#{license[:url]}">#{license[:license]}</a>
-        <<-EOS
+        <<-README
 # #{podspec.name}
 
 ### #{podspec.summary}
@@ -83,15 +86,15 @@ pod '#{podspec.name}'
 ### Authors
 
 #{source_module.author_name}
-EOS
+        README
       else
-        <<-EOS
+        <<-README
 # #{source_module.name}
 
 ### Authors
 
 #{source_module.author_name}
-EOS
+        README
       end
     end
   end

data/lib/jazzy/source_host.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Jazzy
+  # Deal with different source code repositories
+  module SourceHost
+    # Factory to create the right source host
+    def self.create(options)
+      return unless options.source_host_url || options.source_host_files_url
+
+      case options.source_host
+      when :github then GitHub.new
+      when :gitlab then GitLab.new
+      when :bitbucket then BitBucket.new
+      end
+    end
+
+    # Use GitHub as the default behaviour.
+    class GitHub
+      include Config::Mixin
+
+      # Human readable name, appears in UI
+      def name
+        'GitHub'
+      end
+
+      # Jazzy extension with logo
+      def extension
+        name.downcase
+      end
+
+      # Logo image filename within extension
+      def image
+        'gh.png'
+      end
+
+      # URL to link to from logo
+      def url
+        config.source_host_url
+      end
+
+      # URL to link to from a SourceDeclaration.
+      # Compare using `realpath` because `item.file` comes out of
+      # SourceKit/etc.
+      def item_url(item)
+        return unless files_url && item.file
+
+        realpath = item.file.realpath
+        return unless realpath.to_path.start_with?(local_root_realpath)
+
+        path = realpath.relative_path_from(local_root_realpath)
+        fragment =
+          if item.start_line && (item.start_line != item.end_line)
+            item_url_multiline_fragment(item.start_line, item.end_line)
+          else
+            item_url_line_fragment(item.line)
+          end
+
+        "#{files_url}/#{path}##{fragment}"
+      end
+
+      private
+
+      def files_url
+        config.source_host_files_url
+      end
+
+      def local_root_realpath
+        @local_root_realpath ||= config.source_directory.realpath.to_path
+      end
+
+      # Source host's line numbering link scheme
+      def item_url_line_fragment(line)
+        "L#{line}"
+      end
+
+      def item_url_multiline_fragment(start_line, end_line)
+        "L#{start_line}-L#{end_line}"
+      end
+    end
+
+    # GitLab very similar to GitHub
+    class GitLab < GitHub
+      def name
+        'GitLab'
+      end
+
+      def image
+        'gitlab.svg'
+      end
+    end
+
+    # BitBucket has its own line number system
+    class BitBucket < GitHub
+      def name
+        'Bitbucket'
+      end
+
+      def image
+        'bitbucket.svg'
+      end
+
+      def item_url_line_fragment(line)
+        "lines-#{line}"
+      end
+
+      def item_url_multiline_fragment(start_line, end_line)
+        "lines-#{start_line}:#{end_line}"
+      end
+    end
+  end
+end

data/lib/jazzy/source_mark.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jazzy
   class SourceMark
     attr_accessor :name
@@ -8,24 +10,24 @@ module Jazzy
       return unless mark_string
 
       # Format: 'MARK: - NAME -' with dashes optional
-      mark_string.sub!(/^MARK: /, '')
+      mark_content = mark_string.sub(/^MARK: /, '')
 
-      if mark_string.empty?
+      if mark_content.empty?
         # Empty
         return
-      elsif mark_string == '-'
+      elsif mark_content == '-'
         # Separator
         self.has_start_dash = true
         return
       end
 
-      self.has_start_dash = mark_string.start_with?('- ')
-      self.has_end_dash = mark_string.end_with?(' -')
+      self.has_start_dash = mark_content.start_with?('- ')
+      self.has_end_dash = mark_content.end_with?(' -')
 
       start_index = has_start_dash ? 2 : 0
       end_index = has_end_dash ? -3 : -1
 
-      self.name = mark_string[start_index..end_index]
+      self.name = mark_content[start_index..end_index]
     end
 
     def self.new_generic_requirements(requirements)

data/lib/jazzy/source_module.rb

@@ -1,32 +1,32 @@
+# frozen_string_literal: true
+
 require 'uri'
 
 require 'jazzy/config'
 require 'jazzy/source_declaration'
+require 'jazzy/source_host'
 
 module Jazzy
   class SourceModule
     attr_accessor :name
-    attr_accessor :root_path
     attr_accessor :docs
     attr_accessor :doc_coverage
     attr_accessor :doc_structure
     attr_accessor :author_name
-    attr_accessor :github_url
-    attr_accessor :github_file_prefix
     attr_accessor :author_url
     attr_accessor :dash_url
+    attr_accessor :host
 
     def initialize(options, docs, doc_structure, doc_coverage)
       self.docs = docs
-      self.root_path = options.source_directory
       self.doc_structure = doc_structure
       self.doc_coverage = doc_coverage
       self.name = options.module_name
       self.author_name = options.author_name
-      self.github_url = options.github_url
-      self.github_file_prefix = options.github_file_prefix
       self.author_url = options.author_url
+      self.host = SourceHost.create(options)
       return unless options.dash_url
+
       self.dash_url =
         "dash-feed://#{ERB::Util.url_encode(options.dash_url.to_s)}"
     end