jazzy 0.13.5 → 0.14.1

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jazzy
-  VERSION = '0.13.5'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.14.1' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/highlighter.rb

@@ -1,10 +1,24 @@
+# frozen_string_literal: true
+
 require 'rouge'
 
+# While Rouge is downlevel (Rouge PR#1715 unreleased)
+module Rouge
+  module Lexers
+    class Swift
+      prepend :root do
+        rule(/\b(?:async|await|isolated)\b/, Keyword)
+        rule(/\b(?:actor|nonisolated)\b/, Keyword::Declaration)
+      end
+    end
+  end
+end
+
 module Jazzy
   # This module helps highlight code
   module Highlighter
-    SWIFT = 'swift'.freeze
-    OBJC = 'objective_c'.freeze
+    SWIFT = 'swift'
+    OBJC = 'objective_c'
 
     class Formatter < Rouge::Formatters::HTML
       def initialize(language)
@@ -12,7 +26,7 @@ module Jazzy
         super()
       end
 
-      def stream(tokens, &b)
+      def stream(tokens, &block)
         yield "<pre class=\"highlight #{@language}\"><code>"
         super
         yield "</code></pre>\n"

data/lib/jazzy/jazzy_markdown.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'redcarpet'
 require 'rouge'
 require 'rouge/plugins/redcarpet'
@@ -7,32 +9,73 @@ module Jazzy
     # Publish if generated HTML needs math support
     class << self; attr_accessor :has_math; end
 
+    module Footnotes
+      # Global unique footnote ID
+      def self.next_footnote
+        @next_footnote ||= 0
+        @next_footnote += 1
+      end
+
+      # Per-render map from user to global ID
+      attr_accessor :footnotes_hash
+
+      def reset
+        @footnotes_hash = {}
+      end
+
+      def map_footnote(user_num)
+        footnotes_hash.fetch(user_num) do
+          footnotes_hash[user_num] = Footnotes.next_footnote
+        end
+      end
+
+      def footnote_ref(num)
+        mapped = map_footnote(num)
+        "<span class='footnote-ref' id=\"fnref#{mapped}\">" \
+          "<sup><a href=\"#fn#{mapped}\">#{num}</a></sup></span>"
+      end
+
+      # follow native redcarpet: backlink goes before the first </p> tag
+      def footnote_def(text, num)
+        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>'
+      end
+    end
+
+    # rubocop:disable Metrics/ClassLength
     class JazzyHTML < Redcarpet::Render::HTML
       include Redcarpet::Render::SmartyPants
       include Rouge::Plugins::Redcarpet
+      include Footnotes
 
       attr_accessor :default_language
 
       def header(text, header_level)
         text_slug = text.gsub(/[^[[:word:]]]+/, '-')
-                        .downcase
-                        .sub(/^-/, '')
-                        .sub(/-$/, '')
+          .downcase
+          .sub(/^-/, '')
+          .sub(/-$/, '')
 
         "<h#{header_level} id='#{text_slug}' class='heading'>" \
           "#{text}" \
-        "</h#{header_level}>\n"
+          "</h#{header_level}>\n"
       end
 
       def codespan(text)
-        if /^\$\$(.*)\$\$$/m =~ text
-          o = ["<div class='math m-block'>", Regexp.last_match[1], '</div>']
+        case text
+        when /^\$\$(.*)\$\$$/m
+          o = ["</p><div class='math m-block'>",
+               Regexp.last_match[1],
+               '</div><p>']
           Markdown.has_math = true
-        elsif /^\$(.*)\$$/m =~ text
+        when /^\$(.*)\$$/m
           o = ["<span class='math m-inline'>", Regexp.last_match[1], '</span>']
           Markdown.has_math = true
         else
-          o = ['<code>', text, '</code>']
+          o = ['<code>', text.to_s, '</code>']
         end
 
         o[0] + CGI.escapeHTML(o[1]) + o[2]
@@ -79,10 +122,10 @@ module Jazzy
         # any one of our special list types
         (#{SPECIAL_LIST_TYPES.map(&Regexp.method(:escape)).join('|')})
         [\s:] # followed by either a space or a colon
-      }ix
+        }ix.freeze
 
       ELIDED_LI_TOKEN =
-        '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'.freeze
+        '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'
 
       def list_item(text, _list_type)
         if text =~ SPECIAL_LIST_TYPE_REGEX
@@ -90,30 +133,58 @@ module Jazzy
           if UNIQUELY_HANDLED_CALLOUTS.include? type.downcase
             return ELIDED_LI_TOKEN
           end
-          return render_aside(type, text.sub(/#{Regexp.escape(type)}:\s+/, ''))
+
+          return render_list_aside(type,
+                                   text.sub(/#{Regexp.escape(type)}:\s+/, ''))
         end
-        str = '<li>'
-        str << text.strip
-        str << "</li>\n"
+        "<li>#{text.strip}</li>\n"
+      end
+
+      def render_list_aside(type, text)
+        "</ul>#{render_aside(type, text).chomp}<ul>\n"
       end
 
       def render_aside(type, text)
         <<-HTML
-</ul><div class="aside aside-#{type.underscore.tr('_', '-')}">
+<div class="aside aside-#{type.underscore.tr('_', '-')}">
     <p class="aside-title">#{type.underscore.humanize}</p>
     #{text}
-</div><ul>
+</div>
         HTML
       end
 
       def list(text, list_type)
         elided = text.gsub!(ELIDED_LI_TOKEN, '')
         return if text =~ /\A\s*\Z/ && elided
-        str = "\n"
-        str << (list_type == :ordered ? "<ol>\n" : "<ul>\n")
-        str << text
-        str << (list_type == :ordered ? "</ol>\n" : "</ul>\n")
-        str.gsub(%r{\n?<ul>\n<\/ul>}, '')
+
+        tag = list_type == :ordered ? 'ol' : 'ul'
+        "\n<#{tag}>\n#{text}</#{tag}>\n"
+          .gsub(%r{\n?<ul>\n?</ul>}, '')
+      end
+
+      # List from
+      # https://developer.apple.com/documentation/xcode/formatting-your-documentation-content#Add-Notes-and-Other-Asides
+      DOCC_CALLOUTS = %w[note
+                         important
+                         warning
+                         tip
+                         experiment].freeze
+
+      DOCC_CALLOUT_REGEX = %r{
+        \A\s* # optional leading spaces
+        (?:<p>\s*)? # optional opening p tag
+        # any one of the callout names
+        (#{DOCC_CALLOUTS.map(&Regexp.method(:escape)).join('|')})
+        : # followed directly by a colon
+      }ix.freeze
+
+      def block_quote(html)
+        if html =~ DOCC_CALLOUT_REGEX
+          type = Regexp.last_match[1]
+          render_aside(type, html.sub(/#{Regexp.escape(type)}:\s*/, ''))
+        else
+          "\n<blockquote>\n#{html}</blockquote>\n"
+        end
       end
 
       def block_code(code, language)
@@ -124,6 +195,7 @@ module Jazzy
         Highlighter::Formatter.new(lexer.tag)
       end
     end
+    # rubocop:enable Metrics/ClassLength
 
     REDCARPET_OPTIONS = {
       autolink: true,
@@ -133,6 +205,7 @@ module Jazzy
       space_after_headers: false,
       tables: true,
       lax_spacing: true,
+      footnotes: true,
     }.freeze
 
     # Spot and capture returns & param HTML for separate display.
@@ -142,24 +215,25 @@ module Jazzy
       def reset
         @returns = nil
         @parameters = {}
+        super
       end
 
-      INTRO_PAT = '\A(?<intro>\s*(<p>\s*)?)'.freeze
-      OUTRO_PAT = '(?<outro>.*)\z'.freeze
+      INTRO_PAT = '\A(?<intro>\s*(<p>\s*)?)'
+      OUTRO_PAT = '(?<outro>.*)\z'
 
-      RETURNS_REGEX = /#{INTRO_PAT}returns:#{OUTRO_PAT}/im
+      RETURNS_REGEX = /#{INTRO_PAT}returns:#{OUTRO_PAT}/im.freeze
 
-      IDENT_PAT = '(?<param>\S+)'.freeze
+      IDENT_PAT = '(?<param>\S+)'
 
       # Param formats: normal swift, objc via sourcekitten, and
       # possibly inside 'Parameters:'
-      PARAM_PAT1 = "(parameter +#{IDENT_PAT}\\s*:)".freeze
-      PARAM_PAT2 = "(parameter:\\s*#{IDENT_PAT}\\s+)".freeze
-      PARAM_PAT3 = "(#{IDENT_PAT}\\s*:)".freeze
+      PARAM_PAT1 = "(parameter +#{IDENT_PAT}\\s*:)"
+      PARAM_PAT2 = "(parameter:\\s*#{IDENT_PAT}\\s+)"
+      PARAM_PAT3 = "(#{IDENT_PAT}\\s*:)"
 
-      PARAM_PAT = "(?:#{PARAM_PAT1}|#{PARAM_PAT2}|#{PARAM_PAT3})".freeze
+      PARAM_PAT = "(?:#{PARAM_PAT1}|#{PARAM_PAT2}|#{PARAM_PAT3})"
 
-      PARAM_REGEX = /#{INTRO_PAT}#{PARAM_PAT}#{OUTRO_PAT}/im
+      PARAM_REGEX = /#{INTRO_PAT}#{PARAM_PAT}#{OUTRO_PAT}/im.freeze
 
       def list_item(text, _list_type)
         if text =~ RETURNS_REGEX
@@ -187,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
@@ -204,7 +285,7 @@ module Jazzy
     class JazzyCopyright < Redcarpet::Render::HTML
       def link(link, _title, content)
         %(<a class="link" href="#{link}" target="_blank" \
-rel="external">#{content}</a>)
+rel="external noopener">#{content}</a>)
       end
     end
 

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/access_control_level.rb

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

data/lib/jazzy/source_declaration/type.rb

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

data/lib/jazzy/source_declaration.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 require 'jazzy/source_declaration/access_control_level'
 require 'jazzy/source_declaration/type'
 
-# rubocop:disable Metrics/ClassLength
 module Jazzy
+  # rubocop:disable Metrics/ClassLength
   class SourceDeclaration
     # kind of declaration (e.g. class, variable, function)
     attr_accessor :type
@@ -39,7 +41,7 @@ module Jazzy
     attr_accessor :parent_in_docs
 
     # counterpart of parent_in_docs
-    attr_accessor :children
+    attr_reader :children
 
     def children=(new_children)
       # Freeze to ensure that parent_in_docs stays in sync
@@ -76,7 +78,7 @@ module Jazzy
     # of the extended objc class and the category name itself, i.e.
     # ["NSString", "MyMethods"], nil otherwise.
     def objc_category_name
-      name.split(/[\(\)]/) if type.objc_category?
+      name.split(/[()]/) if type.objc_category?
     end
 
     def swift_objc_extension?
@@ -136,6 +138,7 @@ module Jazzy
     attr_accessor :unavailable_message
     attr_accessor :generic_requirements
     attr_accessor :inherited_types
+    attr_accessor :async
 
     def usage_discouraged?
       unavailable || deprecated
@@ -151,6 +154,7 @@ module Jazzy
       # Workaround functions sharing names with
       # different argument types (f(a:Int) vs. f(a:String))
       return result unless type.swift_global_function?
+
       result + "_#{type_usr}"
     end
 
@@ -175,6 +179,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
 
@@ -184,6 +189,14 @@ module Jazzy
         (swift? && usr && modulename.nil?)
     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
       if file = alternative_abstract_file
         Pathname(file).read
@@ -201,7 +214,9 @@ module Jazzy
       return [] unless
         Config.instance.abstract_glob_configured &&
         Config.instance.abstract_glob
+
       Config.instance.abstract_glob.select { |e| File.file? e }
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/jazzy/source_document.rb

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