jazzy 0.13.4 → 0.14.0

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
@@ -138,12 +139,12 @@ module Jazzy
     end
 
     def self.sanitize_filename(doc)
-      unsafe_filename = doc.url_name || doc.name
+      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'] ||
@@ -325,19 +323,19 @@ module Jazzy
         end
     end
 
-    def self.should_mark_undocumented(filepath)
-      source_directory = Config.instance.source_directory.to_s
-      (filepath || '').start_with?(source_directory)
+    # Call things undocumented if they were compiled properly
+    # and came from our module.
+    def self.should_mark_undocumented(declaration)
+      declaration.usr && !declaration.modulename
     end
 
     def self.process_undocumented_token(doc, declaration)
       make_default_doc_info(declaration)
 
-      filepath = doc['key.filepath']
-
-      if !declaration.swift? || should_mark_undocumented(filepath)
+      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'] || '',
@@ -405,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
 
@@ -491,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
@@ -511,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)
@@ -559,19 +558,20 @@ 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']
         declaration.usr = doc['key.usr']
+        declaration.type_usr = doc['key.typeusr']
         declaration.modulename = doc['key.modulename']
         declaration.name = documented_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.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