jazzy 0.13.7 → 0.14.2

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,22 +272,25 @@ module Jazzy
 
     def self.make_default_doc_info(declaration)
       # @todo: Fix these
-      declaration.line = nil
-      declaration.column = nil
       declaration.abstract = ''
       declaration.parameters = []
       declaration.children = []
     end
 
+    def self.attribute?(doc, attr_name)
+      doc['key.attributes']&.find do |attribute|
+        attribute['key.attribute'] == "source.decl.attribute.#{attr_name}"
+      end
+    end
+
     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?
+      attribute?(doc, 'available')
+    end
+
+    def self.spi_attribute?(doc)
+      attribute?(doc, '_spi')
     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:')
 
@@ -302,10 +308,31 @@ module Jazzy
         return false
       end
 
-      # Document enum elements, since we can't tell their ACL.
+      # Only document @_spi declarations in some scenarios
+      return false unless should_document_spi?(doc)
+
+      # Don't document declarations excluded by the min_acl setting
+      if type.swift_extension?
+        should_document_swift_extension?(doc)
+      else
+        should_document_acl?(type, doc)
+      end
+    end
+
+    # Check visibility: SPI
+    def self.should_document_spi?(doc)
+      spi_ok = @min_acl < SourceDeclaration::AccessControlLevel.public ||
+               Config.instance.include_spi_declarations ||
+               (!spi_attribute?(doc) && !doc['key.symgraph_spi'])
+
+      @stats.add_spi_skipped unless spi_ok
+      spi_ok
+    end
+
+    # Check visibility: access control
+    def self.should_document_acl?(type, doc)
+      # Include all enum elements for now, can't tell their ACL.
       return true if type.swift_enum_element?
-      # Document extensions if they might have parts covered by the ACL.
-      return should_document_swift_extension?(doc) if type.swift_extension?
 
       acl_ok = SourceDeclaration::AccessControlLevel.from_doc(doc) >= @min_acl
       unless acl_ok
@@ -314,9 +341,9 @@ module Jazzy
       end
       acl_ok
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
-    # rubocop:enable Metrics/PerceivedComplexity
 
+    # Document extensions if they add protocol conformances, or have any
+    # member that needs to be documented.
     def self.should_document_swift_extension?(doc)
       doc['key.inheritedtypes'] ||
         Array(doc['key.substructure']).any? do |subdoc|
@@ -328,7 +355,9 @@ module Jazzy
     # Call things undocumented if they were compiled properly
     # and came from our module.
     def self.should_mark_undocumented(declaration)
-      declaration.usr && !declaration.modulename
+      declaration.usr &&
+        (declaration.modulename.nil? ||
+         declaration.modulename == Config.instance.module_name)
     end
 
     def self.process_undocumented_token(doc, declaration)
@@ -337,6 +366,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 +434,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 +520,18 @@ module Jazzy
         end
 
       # @available attrs only in compiler 'interface' style
-      available_attrs = extract_availability(doc['key.doc.declaration'] || '')
+      extract_availability(doc['key.doc.declaration'] || '')
+        .concat(extract_attributes(annotated_decl_attrs))
+        .push(decl)
+        .join("\n")
+    end
 
-      available_attrs.concat(extract_attributes(annotated_decl_attrs))
-                     .push(decl)
-                     .join("\n")
+    # Exclude non-async routines that accept async closures
+    def self.swift_async?(fully_annotated_decl)
+      document = REXML::Document.new(fully_annotated_decl)
+      !document.elements['/*/syntaxtype.keyword[text()="async"]'].nil?
+    rescue StandardError
+      nil
     end
 
     # Strip default property attributes because libclang
@@ -510,12 +547,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)
@@ -536,7 +575,9 @@ module Jazzy
         end
         declaration = SourceDeclaration.new
         declaration.parent_in_code = parent
-        declaration.type = SourceDeclaration::Type.new(doc['key.kind'])
+        declaration.type =
+          SourceDeclaration::Type.new(doc['key.kind'],
+                                      doc['key.fully_annotated_decl'])
         declaration.typename = doc['key.typename']
         declaration.objc_name = doc['key.name']
         documented_name = if Config.instance.hide_objc? && doc['key.swift_name']
@@ -558,8 +599,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 +611,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']
@@ -581,12 +622,19 @@ module Jazzy
         inherited_types = doc['key.inheritedtypes'] || []
         declaration.inherited_types =
           inherited_types.map { |type| type['key.name'] }.compact
+        declaration.async =
+          doc['key.symgraph_async'] ||
+          if xml_declaration = doc['key.fully_annotated_decl']
+            swift_async?(xml_declaration)
+          end
 
         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 +646,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 +668,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 +694,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 +738,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 +764,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)
@@ -783,7 +836,9 @@ module Jazzy
       extensions.each do |ext|
         ext.children = ext.children.select do |ext_member|
           proto_member = protocol.children.find do |p|
-            p.name == ext_member.name && p.type == ext_member.type
+            p.name == ext_member.name &&
+              p.type == ext_member.type &&
+              p.async == ext_member.async
           end
 
           # Extension-only method, keep.
@@ -810,6 +865,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 +875,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 +891,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 +936,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 +970,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 +1001,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
 

data/lib/jazzy/stats.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 module Jazzy
   # Collect + report metadata about a processed module
   class Stats
     include Config::Mixin
 
-    attr_reader :documented, :acl_skipped
-    attr_reader :undocumented_decls
+    attr_reader :documented, :acl_skipped, :spi_skipped, :undocumented_decls
 
     def add_documented
       @documented += 1
@@ -14,6 +15,10 @@ module Jazzy
       @acl_skipped += 1
     end
 
+    def add_spi_skipped
+      @spi_skipped += 1
+    end
+
     def add_undocumented(decl)
       @undocumented_decls << decl
     end
@@ -31,7 +36,7 @@ module Jazzy
     end
 
     def initialize
-      @documented = @acl_skipped = 0
+      @documented = @acl_skipped = @spi_skipped = 0
       @undocumented_decls = []
     end
 
@@ -53,10 +58,16 @@ module Jazzy
           "#{symbol_or_symbols(acl_skipped)} " \
           '(use `--min-acl` to specify a different minimum ACL)'
       end
+
+      if spi_skipped > 0
+        puts "skipped #{spi_skipped} SPI #{symbol_or_symbols(spi_skipped)} " \
+          '(use `--include-spi-declarations` to include these)'
+      end
     end
 
     def doc_coverage
       return 0 if acl_included == 0
+
       (100 * documented) / acl_included
     end
 

data/lib/jazzy/symbol_graph/constraint.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jazzy
   module SymbolGraph
     # Constraint is a tidied-up JSON object, used by both Symbol and
@@ -27,6 +29,7 @@ module Jazzy
       def self.new_hash(hash)
         kind = KIND_MAP[hash[:kind]]
         raise "Unknown constraint kind '#{kind}'" unless kind
+
         lhs = hash[:lhs].sub(/^Self\./, '')
         rhs = hash[:rhs].sub(/^Self\./, '')
         new(kind, lhs, rhs)
@@ -62,6 +65,7 @@ module Jazzy
              path_components.include?(hash[:rhs])
             next nil
           end
+
           Constraint.new_hash(hash)
         end.compact
       end
@@ -89,6 +93,6 @@ end
 
 class Array
   def to_where_clause
-    empty? ? '' : ' where ' + map(&:to_swift).join(', ')
+    empty? ? '' : " where #{map(&:to_swift).join(', ')}"
   end
 end

data/lib/jazzy/symbol_graph/ext_node.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jazzy
   module SymbolGraph
     # For extensions we need to track constraints of the extended type
@@ -68,7 +70,7 @@ module Jazzy
       def full_declaration
         decl = "extension #{name}"
         unless conformances.empty?
-          decl += ' : ' + conformances.join(', ')
+          decl += " : #{conformances.join(', ')}"
         end
         decl + all_constraints.ext.to_where_clause
       end