jazzy 0.14.0 → 0.14.3

data/lib/jazzy/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jazzy
-  VERSION = '0.14.0' unless defined? Jazzy::VERSION
+  VERSION = '0.14.3' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/jazzy_markdown.rb

@@ -40,7 +40,8 @@ module Jazzy
         mapped = map_footnote(num)
         "\n<li><div class='footnote-def' id=\"fn#{mapped}\">" +
           text.sub(%r{(?=</p>)},
-                   "&nbsp;<a href=\"#fnref#{mapped}\">&#8617;</a></div></li>")
+                   "&nbsp;<a href=\"#fnref#{mapped}\">&#8617;</a>") +
+          '</div></li>'
       end
     end
 
@@ -66,7 +67,9 @@ module Jazzy
       def codespan(text)
         case text
         when /^\$\$(.*)\$\$$/m
-          o = ["<div class='math m-block'>", Regexp.last_match[1], '</div>']
+          o = ["</p><div class='math m-block'>",
+               Regexp.last_match[1],
+               '</div><p>']
           Markdown.has_math = true
         when /^\$(.*)\$$/m
           o = ["<span class='math m-inline'>", Regexp.last_match[1], '</span>']
@@ -258,12 +261,19 @@ module Jazzy
       @markdown ||= Redcarpet::Markdown.new(renderer, REDCARPET_OPTIONS)
     end
 
+    # Produces <p>-delimited block content
     def self.render(markdown_text, default_language = nil)
       renderer.reset
       renderer.default_language = default_language
       markdown.render(markdown_text)
     end
 
+    # Produces <span>-delimited inline content
+    def self.render_inline(markdown_text, default_language = nil)
+      render(markdown_text, default_language)
+        .sub(%r{^<p>(.*)</p>$}, '<span>\1</span>')
+    end
+
     def self.rendered_returns
       renderer.returns
     end
@@ -275,7 +285,7 @@ module Jazzy
     class JazzyCopyright < Redcarpet::Render::HTML
       def link(link, _title, content)
         %(<a class="link" href="#{link}" target="_blank" \
-rel="noopener" rel="external">#{content}</a>)
+rel="external noopener">#{content}</a>)
       end
     end
 

data/lib/jazzy/search_builder.rb

@@ -6,17 +6,15 @@ module Jazzy
       decls = source_module.all_declarations.select do |d|
         d.type && d.name && !d.name.empty?
       end
-      index = 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.to_h
-      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/type.rb

@@ -12,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
@@ -115,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?
@@ -255,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',
@@ -269,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

@@ -138,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
@@ -182,10 +183,20 @@ module Jazzy
       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

data/lib/jazzy/sourcekitten.rb

@@ -277,12 +277,18 @@ module Jazzy
       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']
+      attribute?(doc, 'available')
+    end
 
-      !doc['key.attributes'].select do |attribute|
-        attribute.values.first == 'source.decl.attribute.available'
-      end.empty?
+    def self.spi_attribute?(doc)
+      attribute?(doc, '_spi')
     end
 
     def self.should_document?(doc)
@@ -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
@@ -315,6 +342,8 @@ module Jazzy
       acl_ok
     end
 
+    # 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|
@@ -326,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)
@@ -495,6 +526,14 @@ module Jazzy
         .join("\n")
     end
 
+    # 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
     # adds them all, even if absent in the original source code.
     DEFAULT_ATTRIBUTES = %w[atomic readwrite assign unsafe_unretained].freeze
@@ -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']
@@ -581,6 +622,11 @@ 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)
 
@@ -790,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.

data/lib/jazzy/stats.rb

@@ -5,7 +5,7 @@ module Jazzy
   class Stats
     include Config::Mixin
 
-    attr_reader :documented, :acl_skipped, :undocumented_decls
+    attr_reader :documented, :acl_skipped, :spi_skipped, :undocumented_decls
 
     def add_documented
       @documented += 1
@@ -15,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
@@ -32,7 +36,7 @@ module Jazzy
     end
 
     def initialize
-      @documented = @acl_skipped = 0
+      @documented = @acl_skipped = @spi_skipped = 0
       @undocumented_decls = []
     end
 
@@ -54,6 +58,11 @@ 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

data/lib/jazzy/symbol_graph/graph.rb

@@ -78,8 +78,13 @@ module Jazzy
 
       # Protocol conformance is redundant if it's unconditional
       # and already expressed in the type's declaration.
+      #
+      # Skip implementation-detail conformances.
       def redundant_conformance?(rel, type, protocol)
-        type && rel.constraints.empty? && type.conformance?(protocol)
+        return false unless type
+
+        (rel.constraints.empty? && type.conformance?(protocol)) ||
+          (type.actor? && rel.actor_protocol?)
       end
 
       # source is a member/protocol requirement of target
@@ -123,7 +128,7 @@ module Jazzy
                (target_parent = target.parent) &&
                target_parent.is_a?(SymNode)
           # Could probably figure this out with demangle, but...
-          warn "Can't resolve membership of default implementation "\
+          warn "Can't resolve membership of default implementation " \
             "#{source.symbol.usr}."
           source.unlisted = true
           return

data/lib/jazzy/symbol_graph/relationship.rb

@@ -22,6 +22,12 @@ module Jazzy
         kind == :defaultImplementationOf
       end
 
+      # Protocol conformances added by compiler to actor decls that
+      # users aren't interested in.
+      def actor_protocol?
+        %w[Actor Sendable].include?(target_fallback)
+      end
+
       def initialize(hash)
         kind = hash[:kind]
         unless KINDS.include?(kind)

data/lib/jazzy/symbol_graph/sym_node.rb

@@ -25,6 +25,7 @@ module Jazzy
 
     # A SymNode is a node of the reconstructed syntax tree holding a symbol.
     # It can turn itself into SourceKit and helps decode extensions.
+    # rubocop:disable Metrics/ClassLength
     class SymNode < BaseNode
       attr_accessor :symbol
       attr_writer :override
@@ -61,6 +62,10 @@ module Jazzy
         symbol.kind.end_with?('protocol')
       end
 
+      def actor?
+        symbol.kind.end_with?('actor')
+      end
+
       def constraints
         symbol.constraints
       end
@@ -112,8 +117,13 @@ module Jazzy
         " : #{superclass_name}"
       end
 
+      # approximately...
+      def async?
+        symbol.declaration =~ /\basync\b[^)]*$/
+      end
+
       def full_declaration
-        symbol.availability
+        symbol.attributes
           .append(symbol.declaration + inherits_clause + where_clause)
           .join("\n")
       end
@@ -130,6 +140,7 @@ module Jazzy
           'key.accessibility' => symbol.acl,
           'key.parsed_decl' => declaration,
           'key.annotated_decl' => xml_declaration,
+          'key.symgraph_async' => async?,
         }
         if docs = symbol.doc_comments
           hash['key.doc.comment'] = docs
@@ -147,6 +158,7 @@ module Jazzy
         unless children.empty?
           hash['key.substructure'] = children_to_sourcekit
         end
+        hash['key.symgraph_spi'] = true if symbol.spi
 
         hash
       end
@@ -159,5 +171,6 @@ module Jazzy
         symbol <=> other.symbol
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/jazzy/symbol_graph/symbol.rb

@@ -10,10 +10,11 @@ module Jazzy
       attr_accessor :declaration
       attr_accessor :kind
       attr_accessor :acl
+      attr_accessor :spi
       attr_accessor :location # can be nil, keys :filename :line :character
       attr_accessor :constraints # array, can be empty
       attr_accessor :doc_comments # can be nil
-      attr_accessor :availability # array, can be empty
+      attr_accessor :attributes # array, can be empty
       attr_accessor :generic_type_params # set, can be empty
       attr_accessor :parameter_names # array, can be nil
 
@@ -24,13 +25,14 @@ module Jazzy
       def initialize(hash)
         self.usr = hash[:identifier][:precise]
         self.path_components = hash[:pathComponents]
-        raw_decl = hash[:declarationFragments].map { |f| f[:spelling] }.join
-        init_kind(hash[:kind][:identifier])
+        raw_decl, keywords = parse_decl_fragments(hash[:declarationFragments])
+        init_kind(hash[:kind][:identifier], keywords)
         init_declaration(raw_decl)
         if func_signature = hash[:functionSignature]
           init_func_signature(func_signature)
         end
         init_acl(hash[:accessLevel])
+        self.spi = hash[:spi]
         if location = hash[:location]
           init_location(location)
         end
@@ -38,10 +40,20 @@ module Jazzy
         if comments_hash = hash[:docComment]
           init_doc_comments(comments_hash)
         end
-        init_availability(hash[:availability] || [])
+        init_attributes(hash[:availability] || [])
         init_generic_type_params(hash)
       end
 
+      def parse_decl_fragments(fragments)
+        decl = ''
+        keywords = Set.new
+        fragments.each do |frag|
+          decl += frag[:spelling]
+          keywords.add(frag[:spelling]) if frag[:kind] == 'keyword'
+        end
+        [decl, keywords]
+      end
+
       # Repair problems with SymbolGraph's declprinter
 
       def init_declaration(raw_decl)
@@ -87,17 +99,22 @@ module Jazzy
         'static.subscript' => 'function.subscript',
         'typealias' => 'typealias',
         'associatedtype' => 'associatedtype',
+        'actor' => 'actor',
       }.freeze
 
       # We treat 'static var' differently to 'class var'
-      def adjust_kind_for_declaration(kind)
-        return kind unless declaration =~ /\bstatic\b/
+      # We treat actors as first-class entities
+      def adjust_kind_for_declaration(kind, keywords)
+        if kind == 'swift.class' && keywords.member?('actor')
+          return 'swift.actor'
+        end
+        return kind unless keywords.member?('static')
 
         kind.gsub(/type/, 'static')
       end
 
-      def init_kind(kind)
-        adjusted = adjust_kind_for_declaration(kind)
+      def init_kind(kind, keywords)
+        adjusted = adjust_kind_for_declaration(kind, keywords)
         sourcekit_kind = KIND_MAP[adjusted.sub('swift.', '')]
         raise "Unknown symbol kind '#{kind}'" unless sourcekit_kind
 
@@ -159,8 +176,8 @@ module Jazzy
       # Availability
       # Re-encode this as Swift.  Should really teach Jazzy about these,
       # could maybe then do something smarter here.
-      def init_availability(avail_hash_list)
-        self.availability = avail_hash_list.map do |avail|
+      def availability_attributes(avail_hash_list)
+        avail_hash_list.map do |avail|
           str = '@available('
           if avail[:isUnconditionallyDeprecated]
             str += '*, deprecated'
@@ -190,6 +207,15 @@ module Jazzy
         str
       end
 
+      def spi_attributes
+        spi ? ['@_spi(Unknown)'] : []
+      end
+
+      def init_attributes(avail_hash_list)
+        self.attributes =
+          availability_attributes(avail_hash_list) + spi_attributes
+      end
+
       # Sort order
       include Comparable
 

data/lib/jazzy/symbol_graph.rb

@@ -14,27 +14,24 @@ require 'jazzy/symbol_graph/ext_node'
 
 module Jazzy
   module SymbolGraph
-    # Run `swift symbolgraph-extract` with configured args,
-    # parse the results, and return as JSON in SourceKit[ten]
+    # Find swift symbol graph files, either having been passed
+    # in directly, or generated by running`swift symbolgraph-extract`
+    # with configured args.
+    # Then parse the results, and return as JSON in SourceKit[ten]
     # format.
     def self.build(config)
-      Dir.mktmpdir do |tmp_dir|
-        args = arguments(config, tmp_dir)
+      if config.symbolgraph_directory.nil?
+        Dir.mktmpdir do |tmp_dir|
+          args = arguments(config, tmp_dir)
 
-        Executable.execute_command('swift',
-                                   args.unshift('symbolgraph-extract'),
-                                   true) # raise on error
+          Executable.execute_command('swift',
+                                     args.unshift('symbolgraph-extract'),
+                                     true) # raise on error
 
-        Dir[tmp_dir + '/*.symbols.json'].map do |filename|
-          # The @ part is for extensions in our module (before the @)
-          # of types in another module (after the @).
-          filename =~ /(.*?)(@(.*?))?\.symbols/
-          module_name = Regexp.last_match[3] || Regexp.last_match[1]
-          {
-            filename =>
-              Graph.new(File.read(filename), module_name).to_sourcekit,
-          }
-        end.to_json
+          parse_symbols(tmp_dir)
+        end
+      else
+        parse_symbols(config.symbolgraph_directory.to_s)
       end
     end
 
@@ -47,8 +44,8 @@ module Jazzy
       user_args = config.build_tool_arguments.join
 
       if user_args =~ /-(?:module-name|minimum-access-level|output-dir)/
-        raise 'error: `--build-tool-arguments` for '\
-          "`--swift-build-tool symbolgraph` can't use `-module`, "\
+        raise 'error: `--build-tool-arguments` for ' \
+          "`--swift-build-tool symbolgraph` can't use `-module`, " \
           '`-minimum-access-level`, or `-output-dir`.'
       end
 
@@ -69,6 +66,20 @@ module Jazzy
       args + config.build_tool_arguments
     end
 
+    # Parse the symbol files in the given directory
+    def self.parse_symbols(directory)
+      Dir[directory + '/*.symbols.json'].map do |filename|
+        # The @ part is for extensions in our module (before the @)
+        # of types in another module (after the @).
+        File.basename(filename) =~ /(.*?)(@(.*?))?\.symbols/
+        module_name = Regexp.last_match[3] || Regexp.last_match[1]
+        {
+          filename =>
+            Graph.new(File.read(filename), module_name).to_sourcekit,
+        }
+      end.to_json
+    end
+
     # Get the SDK path.  On !darwin this just isn't needed.
     def self.sdk(config)
       `xcrun --show-sdk-path --sdk #{config.sdk}`.chomp