jazzy 0.13.7 → 0.14.0

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,18 +1,19 @@
+# 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.map 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,
          }.reject { |_, v| v.nil? || v.empty? }]
-      end
-      ]
+      end.to_h
       File.open(File.join(output_dir, 'search.json'), 'w') do |f|
         f.write(index.to_json)
       end

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?
@@ -151,6 +153,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,6 +178,7 @@ 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
 
@@ -201,7 +205,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_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
@@ -151,7 +153,7 @@ module Jazzy
         Type.new('Overview')
       end
 
-      MARKDOWN_KIND = 'document.markdown'.freeze
+      MARKDOWN_KIND = 'document.markdown'
 
       def self.markdown
         Type.new(MARKDOWN_KIND)

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

data/lib/jazzy/sourcekitten.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'pathname'
 require 'shellwords'
@@ -12,7 +14,7 @@ require 'jazzy/source_declaration'
 require 'jazzy/source_mark'
 require 'jazzy/stats'
 
-ELIDED_AUTOLINK_TOKEN = '36f8f5912051ae747ef441d6511ca4cb'.freeze
+ELIDED_AUTOLINK_TOKEN = '36f8f5912051ae747ef441d6511ca4cb'
 
 def autolink_regex(middle_regex, after_highlight)
   start_tag_re, end_tag_re =
@@ -29,16 +31,15 @@ class String
     gsub(autolink_regex(middle_regex, after_highlight)) do
       original = Regexp.last_match(0)
       start_tag, raw_name, end_tag = Regexp.last_match.captures
-      link_target = yield(CGI.unescape_html(raw_name))
+      link_target, display_name = yield(CGI.unescape_html(raw_name))
 
       if link_target &&
          !link_target.type.extension? &&
          link_target.url &&
          link_target.url != doc_url.split('#').first && # Don't link to parent
          link_target.url != doc_url # Don't link to self
-        start_tag +
-          "<a href=\"#{ELIDED_AUTOLINK_TOKEN}#{link_target.url}\">" +
-          raw_name + '</a>' + end_tag
+        "#{start_tag}<a href=\"#{ELIDED_AUTOLINK_TOKEN}#{link_target.url}\">" \
+          "#{CGI.escape_html(display_name)}</a>#{end_tag}"
       else
         original
       end
@@ -74,8 +75,8 @@ module Jazzy
         children = category['children'].flat_map do |name|
           docs_with_name, docs = docs.partition { |doc| doc.name == name }
           if docs_with_name.empty?
-            STDERR.puts 'WARNING: No documented top-level declarations match ' \
-                        "name \"#{name}\" specified in categories file"
+            warn 'WARNING: No documented top-level declarations match ' \
+              "name \"#{name}\" specified in categories file"
           end
           docs_with_name
         end
@@ -129,7 +130,7 @@ module Jazzy
     def self.merge_consecutive_marks(docs)
       prev_mark = nil
       docs.each do |doc|
-        if prev_mark && prev_mark.can_merge?(doc.mark)
+        if prev_mark&.can_merge?(doc.mark)
           doc.mark = prev_mark
         end
         prev_mark = doc.mark
@@ -141,9 +142,9 @@ module Jazzy
       unsafe_filename = doc.docs_filename
       sanitzation_enabled = Config.instance.use_safe_filenames
       if sanitzation_enabled && !doc.type.name_controlled_manually?
-        return CGI.escape(unsafe_filename).gsub('_', '%5F').tr('%', '_')
+        CGI.escape(unsafe_filename).gsub('_', '%5F').tr('%', '_')
       else
-        return unsafe_filename
+        unsafe_filename
       end
     end
 
@@ -162,11 +163,11 @@ module Jazzy
           # Don't create HTML page for this doc if it doesn't have children
           # Instead, make its link a hash-link on its parent's page
           if doc.typename == '<<error type>>'
-            warn 'A compile error prevented ' + doc.fully_qualified_name +
-                 ' from receiving a unique USR. Documentation may be ' \
-                 'incomplete. Please check for compile errors by running ' \
-                 '`xcodebuild` or `swift build` with arguments ' \
-                 "`#{Config.instance.build_tool_arguments.shelljoin}`."
+            warn "A compile error prevented #{doc.fully_qualified_name} " \
+              'from receiving a unique USR. Documentation may be ' \
+              'incomplete. Please check for compile errors by running ' \
+              '`xcodebuild` or `swift build` with arguments ' \
+              "`#{Config.instance.build_tool_arguments.shelljoin}`."
           end
           id = doc.usr
           unless id
@@ -174,11 +175,11 @@ module Jazzy
             warn "`#{id}` has no USR. First make sure all modules used in " \
               'your project have been imported. If all used modules are ' \
               'imported, please report this problem by filing an issue at ' \
-              'https://github.com/realm/jazzy/issues along with your Xcode ' \
-              'project. If this token is declared in an `#if` block, please ' \
-              'ignore this message.'
+              'https://github.com/realm/jazzy/issues along with your ' \
+              'Xcode project. If this token is declared in an `#if` block, ' \
+              'please ignore this message.'
           end
-          doc.url = doc.parent_in_docs.url + '#/' + id
+          doc.url = "#{doc.parent_in_docs.url}#/#{id}"
         end
       end
     end
@@ -189,6 +190,7 @@ module Jazzy
     # Declarations under outer namespace type (Structures, Classes, etc.)
     def self.subdir_for_doc(doc)
       return [] if doc.type.markdown?
+
       top_level_decl = doc.namespace_path.first
       if top_level_decl.type.name
         [top_level_decl.type.plural_url_name] +
@@ -258,6 +260,7 @@ module Jazzy
         unless xcode = XCInvoke::Xcode.find_swift_version(swift_version)
           raise "Unable to find an Xcode with swift version #{swift_version}."
         end
+
         env = xcode.as_env
       else
         env = ENV
@@ -269,8 +272,6 @@ module Jazzy
 
     def self.make_default_doc_info(declaration)
       # @todo: Fix these
-      declaration.line = nil
-      declaration.column = nil
       declaration.abstract = ''
       declaration.parameters = []
       declaration.children = []
@@ -278,13 +279,12 @@ module Jazzy
 
     def self.availability_attribute?(doc)
       return false unless doc['key.attributes']
+
       !doc['key.attributes'].select do |attribute|
         attribute.values.first == 'source.decl.attribute.available'
       end.empty?
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
-    # rubocop:disable Metrics/PerceivedComplexity
     def self.should_document?(doc)
       return false if doc['key.doc.comment'].to_s.include?(':nodoc:')
 
@@ -314,8 +314,6 @@ module Jazzy
       end
       acl_ok
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
-    # rubocop:enable Metrics/PerceivedComplexity
 
     def self.should_document_swift_extension?(doc)
       doc['key.inheritedtypes'] ||
@@ -337,6 +335,7 @@ module Jazzy
       if !declaration.swift? || should_mark_undocumented(declaration)
         @stats.add_undocumented(declaration)
         return nil if @skip_undocumented
+
         declaration.abstract = undocumented_abstract
       else
         declaration.abstract = Markdown.render(doc['key.doc.comment'] || '',
@@ -404,7 +403,7 @@ module Jazzy
     def self.xml_to_text(xml)
       document = REXML::Document.new(xml)
       REXML::XPath.match(document.root, '//text()').map(&:value).join
-    rescue
+    rescue StandardError
       ''
     end
 
@@ -490,11 +489,10 @@ module Jazzy
         end
 
       # @available attrs only in compiler 'interface' style
-      available_attrs = extract_availability(doc['key.doc.declaration'] || '')
-
-      available_attrs.concat(extract_attributes(annotated_decl_attrs))
-                     .push(decl)
-                     .join("\n")
+      extract_availability(doc['key.doc.declaration'] || '')
+        .concat(extract_attributes(annotated_decl_attrs))
+        .push(decl)
+        .join("\n")
     end
 
     # Strip default property attributes because libclang
@@ -510,12 +508,14 @@ module Jazzy
       attrs = Regexp.last_match[1].split(',').map(&:strip) - DEFAULT_ATTRIBUTES
       attrs_text = attrs.empty? ? '' : " (#{attrs.join(', ')})"
 
-      declaration.sub(/(?<=@property)\s+\(.*?\)/, attrs_text)
-                 .gsub(/\s+/, ' ')
+      declaration
+        .sub(/(?<=@property)\s+\(.*?\)/, attrs_text)
+        .gsub(/\s+/, ' ')
     end
 
     def self.make_substructure(doc, declaration)
       return [] unless subdocs = doc['key.substructure']
+
       make_source_declarations(subdocs,
                                declaration,
                                declaration.mark_for_children)
@@ -558,8 +558,8 @@ module Jazzy
 
         unless declaration.type.name
           raise 'Please file an issue at ' \
-                'https://github.com/realm/jazzy/issues about adding support ' \
-                "for `#{declaration.type.kind}`."
+            'https://github.com/realm/jazzy/issues about adding support ' \
+            "for `#{declaration.type.kind}`."
         end
 
         declaration.file = Pathname(doc['key.filepath']) if doc['key.filepath']
@@ -570,8 +570,8 @@ module Jazzy
         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.line = doc['key.doc.line'] || doc['key.line']
+        declaration.column = doc['key.doc.column'] || doc['key.column']
         declaration.start_line = doc['key.parsed_scope.start']
         declaration.end_line = doc['key.parsed_scope.end']
         declaration.deprecated = doc['key.always_deprecated']
@@ -583,10 +583,12 @@ module Jazzy
           inherited_types.map { |type| type['key.name'] }.compact
 
         next unless make_doc_info(doc, declaration)
+
         declaration.children = make_substructure(doc, declaration)
         next if declaration.type.extension? &&
                 declaration.children.empty? &&
                 !declaration.inherited_types?
+
         declarations << declaration
       end
       declarations
@@ -598,6 +600,7 @@ module Jazzy
     def self.find_generic_requirements(parsed_declaration)
       parsed_declaration =~ /\bwhere\s+(.*)$/m
       return nil unless Regexp.last_match
+
       Regexp.last_match[1].gsub(/\s+/, ' ')
     end
 
@@ -619,6 +622,7 @@ module Jazzy
 
     def self.expand_extension(extension, name_parts, decls)
       return extension if name_parts.empty?
+
       name = name_parts.shift
       candidates = decls.select { |decl| decl.name == name }
       SourceDeclaration.new.tap do |decl|
@@ -644,8 +648,8 @@ module Jazzy
     # Merges redundant declarations when documenting podspecs.
     def self.deduplicate_declarations(declarations)
       duplicate_groups = declarations
-                         .group_by { |d| deduplication_key(d, declarations) }
-                         .values
+        .group_by { |d| deduplication_key(d, declarations) }
+        .values
 
       duplicate_groups.flat_map do |group|
         # Put extended type (if present) before extensions
@@ -688,15 +692,17 @@ module Jazzy
     end
 
     # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/PerceivedComplexity
     # Merges all of the given types and extensions into a single document.
     def self.merge_declarations(decls)
       extensions, typedecls = decls.partition { |d| d.type.extension? }
 
       if typedecls.size > 1
+        info = typedecls
+          .map { |t| "#{t.type.name.downcase} #{t.name}" }
+          .join(', ')
         warn 'Found conflicting type declarations with the same name, which ' \
-          'may indicate a build issue or a bug in Jazzy: ' +
-             typedecls.map { |t| "#{t.type.name.downcase} #{t.name}" }
-                      .join(', ')
+          "may indicate a build issue or a bug in Jazzy: #{info}"
       end
       typedecl = typedecls.first
 
@@ -712,13 +718,14 @@ module Jazzy
       end
 
       # Keep type-aliases separate from any extensions
-      if typedecl && typedecl.type.swift_typealias?
+      if typedecl&.type&.swift_typealias?
         [merge_type_and_extensions(typedecls, []),
          merge_type_and_extensions([], extensions)]
       else
         merge_type_and_extensions(typedecls, extensions)
       end
     end
+    # rubocop:enable Metrics/PerceivedComplexity
     # rubocop:enable Metrics/MethodLength
 
     def self.merge_type_and_extensions(typedecls, extensions)
@@ -810,6 +817,7 @@ module Jazzy
     # (unless they already have a mark)
     def self.merge_objc_declaration_marks(typedecl, extensions)
       return unless typedecl.type.objc_class?
+
       extensions.each do |ext|
         _, category_name = ext.objc_category_name
         ext.children.each { |c| c.mark.name ||= category_name }
@@ -819,7 +827,8 @@ module Jazzy
     # For each extension to be merged, move any MARK from the extension
     # declaration down to the extension contents so it still shows up.
     def self.move_merged_extension_marks(decls)
-      return unless to_be_merged = decls[1..-1]
+      return unless to_be_merged = decls[1..]
+
       to_be_merged.each do |ext|
         child = ext.children.first
         if child && child.mark.empty?
@@ -834,7 +843,7 @@ module Jazzy
     def self.merge_code_declaration(decls)
       first = decls.first
 
-      declarations = decls[1..-1].select do |decl|
+      declarations = decls[1..].select do |decl|
         decl.type.swift_extension? &&
           (decl.other_inherited_types?(@inaccessible_protocols) ||
             (first.type.swift_extension? && decl.constrained_extension?))
@@ -879,9 +888,11 @@ module Jazzy
 
     def self.name_match(name_part, docs)
       return nil unless name_part
+
       wildcard_expansion = Regexp.escape(name_part)
-                                 .gsub('\.\.\.', '[^)]*')
-                                 .gsub(/<.*>/, '')
+        .gsub('\.\.\.', '[^)]*')
+        .gsub(/<.*>/, '')
+
       whole_name_pat = /\A#{wildcard_expansion}\Z/
       docs.find do |doc|
         whole_name_pat =~ doc.name
@@ -911,19 +922,26 @@ module Jazzy
     # - method signatures after they've been processed by the highlighter
     #
     # The `after_highlight` flag is used to differentiate between the two modes.
-    def self.autolink_text(text, doc, root_decls, after_highlight = false)
+    #
+    # DocC link format - follow Xcode and don't display slash-separated parts.
+    # rubocop:disable Metrics/MethodLength
+    def self.autolink_text(text, doc, root_decls, after_highlight: false)
       text.autolink_block(doc.url, '[^\s]+', after_highlight) do |raw_name|
-        parts = raw_name.sub(/^@/, '') # ignore for custom attribute ref
-                        .split(/(?<!\.)\.(?!\.)/) # dot with no neighboring dots
-                        .reject(&:empty?)
+        sym_name =
+          (raw_name[/^<doc:(.*)>$/, 1] || raw_name).sub(/(?<!^)-.+$/, '')
+
+        parts = sym_name
+          .sub(/^@/, '') # ignore for custom attribute ref
+          .split(%r{(?<!\.)[/.](?!\.)}) # dot or slash, but not '...'
+          .reject(&:empty?)
 
         # First dot-separated component can match any ancestor or top-level doc
         first_part = parts.shift
         name_root = ancestor_name_match(first_part, doc) ||
                     name_match(first_part, root_decls)
 
-        # Traverse children via subsequence components, if any
-        name_traversal(parts, name_root)
+        # Traverse children via subsequent components, if any
+        [name_traversal(parts, name_root), sym_name.sub(%r{^.*/}, '')]
       end.autolink_block(doc.url, '[+-]\[\w+(?: ?\(\w+\))? [\w:]+\]',
                          after_highlight) do |raw_name|
         match = raw_name.match(/([+-])\[(\w+(?: ?\(\w+\))?) ([\w:]+)\]/)
@@ -935,42 +953,50 @@ module Jazzy
 
         if name_root
           # Look up the verb in the subject’s children
-          name_match(match[1] + match[3], name_root.children)
+          [name_match(match[1] + match[3], name_root.children), raw_name]
         end
       end.autolink_block(doc.url, '[+-]\w[\w:]*', after_highlight) do |raw_name|
-        name_match(raw_name, doc.children)
+        [name_match(raw_name, doc.children), raw_name]
       end
     end
+    # rubocop:enable Metrics/MethodLength
 
     AUTOLINK_TEXT_FIELDS = %w[return
                               abstract
                               unavailable_message
                               deprecation_message].freeze
 
+    def self.autolink_text_fields(doc, root_decls)
+      AUTOLINK_TEXT_FIELDS.each do |field|
+        if text = doc.send(field)
+          doc.send(field + '=', autolink_text(text, doc, root_decls))
+        end
+      end
+
+      (doc.parameters || []).each do |param|
+        param[:discussion] =
+          autolink_text(param[:discussion], doc, root_decls)
+      end
+    end
+
     AUTOLINK_HIGHLIGHT_FIELDS = %w[declaration
                                    other_language_declaration].freeze
 
+    def self.autolink_highlight_fields(doc, root_decls)
+      AUTOLINK_HIGHLIGHT_FIELDS.each do |field|
+        if text = doc.send(field)
+          doc.send(field + '=',
+                   autolink_text(text, doc, root_decls, after_highlight: true))
+        end
+      end
+    end
+
     def self.autolink(docs, root_decls)
       @autolink_root_decls = root_decls
       docs.each do |doc|
         doc.children = autolink(doc.children, root_decls)
-
-        AUTOLINK_TEXT_FIELDS.each do |field|
-          if text = doc.send(field)
-            doc.send(field + '=', autolink_text(text, doc, root_decls))
-          end
-        end
-
-        AUTOLINK_HIGHLIGHT_FIELDS.each do |field|
-          if text = doc.send(field)
-            doc.send(field + '=', autolink_text(text, doc, root_decls, true))
-          end
-        end
-
-        (doc.parameters || []).each do |param|
-          param[:discussion] =
-            autolink_text(param[:discussion], doc, root_decls)
-        end
+        autolink_text_fields(doc, root_decls)
+        autolink_highlight_fields(doc, root_decls)
       end
     end