RubyGems - jazzy - Versions diffs - 0.11.0 → 0.13.1 - Mend

jazzy 0.11.0 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

checksums.yaml +4 -4
data/.circleci/config.yml +3 -20
data/CHANGELOG.md +133 -0
data/CONTRIBUTING.md +1 -1
data/Gemfile.lock +37 -31
data/README.md +51 -3
data/bin/sourcekitten +0 -0
data/jazzy.gemspec +2 -2
data/lib/jazzy/config.rb +27 -6
data/lib/jazzy/doc.rb +0 -4
data/lib/jazzy/doc_builder.rb +36 -20
data/lib/jazzy/gem_version.rb +1 -1
data/lib/jazzy/highlighter.rb +10 -8
data/lib/jazzy/jazzy_markdown.rb +3 -4
data/lib/jazzy/source_declaration.rb +62 -6
data/lib/jazzy/source_declaration/type.rb +8 -0
data/lib/jazzy/source_mark.rb +11 -0
data/lib/jazzy/sourcekitten.rb +239 -93
data/lib/jazzy/stats.rb +4 -0
data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss +36 -2
data/lib/jazzy/themes/apple/templates/task.mustache +4 -3
data/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss +35 -7
data/lib/jazzy/themes/fullwidth/templates/doc.mustache +1 -1
data/lib/jazzy/themes/fullwidth/templates/task.mustache +4 -3
data/lib/jazzy/themes/jony/assets/css/jazzy.css.scss +35 -2
data/lib/jazzy/themes/jony/templates/task.mustache +4 -3
data/spec/integration_spec.rb +23 -10
metadata +5 -4

data/bin/sourcekitten CHANGED Viewed

Binary file

data/jazzy.gemspec CHANGED Viewed

@@ -5,8 +5,8 @@ require File.expand_path('lib/jazzy/gem_version.rb', File.dirname(__FILE__))
 Gem::Specification.new do |spec|
   spec.name          = 'jazzy'
   spec.version       = Jazzy::VERSION
-  spec.authors       = ['JP Simard', 'Tim Anglade', 'Samuel Giddins']
-  spec.email         = ['jp@realm.io']
+  spec.authors       = ['JP Simard', 'Tim Anglade', 'Samuel Giddins', 'John Fairhurst']
+  spec.email         = ['jp@jpsim.com']
   spec.summary       = 'Soulful docs for Swift & Objective-C.'
   spec.description   = 'Soulful docs for Swift & Objective-C. ' \
                        "Run in your Xcode project's root directory for " \

data/lib/jazzy/config.rb CHANGED Viewed

@@ -102,6 +102,14 @@ module Jazzy
       Pathname(Dir[abs_path][0] || abs_path) # Use existing filesystem spelling
     end
+    def hide_swift?
+      hide_declarations == 'swift'
+    end
+    def hide_objc?
+      hide_declarations == 'objc'
+    end
     # ──────── Build ────────
     # rubocop:disable Layout/AlignParameters
@@ -143,9 +151,9 @@ module Jazzy
       command_line: '--hide-declarations [objc|swift] ',
       description: 'Hide declarations in the specified language. Given that ' \
                    'generating Swift docs only generates Swift declarations, ' \
-                   'this is only really useful to display just the Swift ' \
-                   'declarations & names when generating docs for an ' \
-                   'Objective-C framework.',
+                   'this is useful for hiding a specific interface for ' \
+                   'either Objective-C or mixed Objective-C and Swift ' \
+                   'projects.',
       default: ''
     config_attr :config_file,
@@ -165,9 +173,10 @@ module Jazzy
       description: 'Back-compatibility alias for build_tool_arguments.'
     config_attr :sourcekitten_sourcefile,
-      command_line: ['-s', '--sourcekitten-sourcefile FILEPATH'],
-      description: 'File generated from sourcekitten output to parse',
-      parse: ->(s) { expand_path(s) }
+      command_line: ['-s', '--sourcekitten-sourcefile filepath1,…filepathN',
+                     Array],
+      description: 'File(s) generated from sourcekitten output to parse',
+      parse: ->(paths) { [paths].flatten.map { |path| expand_path(path) } }
     config_attr :source_directory,
       command_line: '--source-directory DIRPATH',
@@ -346,6 +355,18 @@ module Jazzy
                     'Example: https://git.io/v4Bcp'],
       default: []
+    config_attr :custom_categories_unlisted_prefix,
+      description: "Prefix for navigation section names that aren't "\
+                   'explicitly listed in `custom_categories`.',
+      default: 'Other '
+    config_attr :hide_unlisted_documentation,
+      command_line: '--[no-]hide-unlisted-documentation',
+      description: "Don't include documentation in the sidebar from the "\
+                   "`documentation` config value that aren't explicitly "\
+                   'listed in `custom_categories`.',
+      default: false
     config_attr :custom_head,
       command_line: '--head HTML',
       description: 'Custom HTML to inject into <head></head>.',

data/lib/jazzy/doc.rb CHANGED Viewed

@@ -32,10 +32,6 @@ module Jazzy
       config.objc_mode && config.hide_declarations != 'objc'
     end
-    def language
-      objc_first? ? 'Objective-C' : 'Swift'
-    end
     def language_stub
       objc_first? ? 'objc' : 'swift'
     end

data/lib/jazzy/doc_builder.rb CHANGED Viewed

@@ -29,23 +29,36 @@ module Jazzy
     # @return [Array] doc structure comprised of
     #                     section names & child names & URLs
     def self.doc_structure_for_docs(docs)
-      docs.map do |doc|
-        children = doc.children
-                      .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
-                      .flat_map do |child|
-          # FIXME: include arbitrarily nested extensible types
-          [{ name: child.name, url: child.url }] +
-            Array(child.children.select do |sub_child|
-              sub_child.type.swift_extensible? || sub_child.type.extension?
-            end).map do |sub_child|
-              { name: "– #{sub_child.name}", url: sub_child.url }
-            end
+      docs
+        .map do |doc|
+          children = children_for_doc(doc)
+          {
+            section: doc.name,
+            url: doc.url,
+            children: children,
+          }
         end
-        {
-          section: doc.name,
-          url: doc.url,
-          children: children,
-        }
+        .select do |structure|
+          if Config.instance.hide_unlisted_documentation
+            unlisted_prefix = Config.instance.custom_categories_unlisted_prefix
+            structure[:section] != "#{unlisted_prefix}Guides"
+          else
+            true
+          end
+        end
+    end
+    def self.children_for_doc(doc)
+      doc.children
+         .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
+         .flat_map do |child|
+        # FIXME: include arbitrarily nested extensible types
+        [{ name: child.name, url: child.url }] +
+          Array(child.children.select do |sub_child|
+            sub_child.type.swift_extensible? || sub_child.type.extension?
+          end).map do |sub_child|
+            { name: "– #{sub_child.name}", url: sub_child.url }
+          end
       end
     end
@@ -53,8 +66,9 @@ module Jazzy
     # @param [Config] options
     # @return [SourceModule] the documented source module
     def self.build(options)
-      if options.sourcekitten_sourcefile
-        stdout = options.sourcekitten_sourcefile.read
+      if options.sourcekitten_sourcefile_configured
+        stdout = '[' + options.sourcekitten_sourcefile.map(&:read)
+                              .join(',') + ']'
       elsif options.podspec_configured
         pod_documenter = PodspecDocumenter.new(options.podspec)
         stdout = pod_documenter.sourcekitten_output(options)
@@ -329,6 +343,7 @@ module Jazzy
         name:                       item.name,
         abstract:                   abstract,
         declaration:                item.display_declaration,
+        language:                   item.display_language,
         other_language_declaration: item.display_other_language_declaration,
         usr:                        item.usr,
         dash_type:                  item.type.dash_type,
@@ -348,9 +363,10 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
-    def self.make_task(mark, uid, items)
+    def self.make_task(mark, uid, items, doc_model)
       {
         name: mark.name,
+        name_html: (render(doc_model, mark.name) if mark.name),
         uid: URI.encode(uid),
         items: items,
         pre_separator: mark.has_start_dash,
@@ -374,7 +390,7 @@ module Jazzy
         else
           mark_names_counts[uid] = 1
         end
-        make_task(mark, uid, items)
+        make_task(mark, uid, items, mark_children.first)
       end
     end

data/lib/jazzy/gem_version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.11.0'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.13.1'.freeze unless defined? Jazzy::VERSION
 end

data/lib/jazzy/highlighter.rb CHANGED Viewed

@@ -3,6 +3,9 @@ require 'rouge'
 module Jazzy
   # This module helps highlight code
   module Highlighter
+    SWIFT = 'swift'.freeze
+    OBJC = 'objective_c'.freeze
     class Formatter < Rouge::Formatters::HTML
       def initialize(language)
         @language = language
@@ -16,16 +19,15 @@ module Jazzy
       end
     end
-    # What Rouge calls the language
-    def self.default_language
-      if Config.instance.objc_mode
-        'objective_c'
-      else
-        'swift'
-      end
+    def self.highlight_swift(source)
+      highlight(source, SWIFT)
+    end
+    def self.highlight_objc(source)
+      highlight(source, OBJC)
     end
-    def self.highlight(source, language = default_language)
+    def self.highlight(source, language)
       source && Rouge.highlight(source, language, Formatter.new(language))
     end
   end

data/lib/jazzy/jazzy_markdown.rb CHANGED Viewed

@@ -82,21 +82,21 @@ module Jazzy
       def render_aside(type, text)
         <<-HTML
-<div class="aside aside-#{type.underscore.tr('_', '-')}">
+</ul><div class="aside aside-#{type.underscore.tr('_', '-')}">
     <p class="aside-title">#{type.underscore.humanize}</p>
     #{text}
-</div>
+</div><ul>
         HTML
       end
       def list(text, list_type)
         elided = text.gsub!(ELIDED_LI_TOKEN, '')
         return if text =~ /\A\s*\Z/ && elided
-        return text if text =~ /class="aside-title"/
         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>}, '')
       end
       def block_code(code, language)
@@ -112,7 +112,6 @@ module Jazzy
       autolink: true,
       fenced_code_blocks: true,
       no_intra_emphasis: true,
-      quote: true,
       strikethrough: true,
       space_after_headers: false,
       tables: true,

data/lib/jazzy/source_declaration.rb CHANGED Viewed

@@ -1,6 +1,7 @@
 require 'jazzy/source_declaration/access_control_level'
 require 'jazzy/source_declaration/type'
+# rubocop:disable Metrics/ClassLength
 module Jazzy
   class SourceDeclaration
     # kind of declaration (e.g. class, variable, function)
@@ -13,6 +14,14 @@ module Jazzy
       children.any?
     end
+    def swift?
+      type.swift_type?
+    end
+    def highlight_language
+      swift? ? Highlighter::SWIFT : Highlighter::OBJC
+    end
     # When referencing this item from its parent category,
     # include the content or just link to it directly?
     def omit_content_from_parent?
@@ -67,17 +76,32 @@ module Jazzy
       name.split(/[\(\)]/) if type.objc_category?
     end
+    def swift_objc_extension?
+      type.swift_extension? && usr && usr.start_with?('c:objc')
+    end
+    def swift_extension_objc_name
+      return unless type.swift_extension? && usr
+      usr.split('(cs)').last
+    end
+    # The language in the templates for display
+    def display_language
+      return 'Swift' if swift?
+      Config.instance.hide_objc? ? 'Swift' : 'Objective-C'
+    end
     def display_declaration
-      if Config.instance.hide_declarations == 'objc'
-        other_language_declaration
-      else
-        declaration
-      end
+      return declaration if swift?
+      Config.instance.hide_objc? ? other_language_declaration : declaration
     end
     def display_other_language_declaration
       other_language_declaration unless
-        %w[swift objc].include? Config.instance.hide_declarations
+        Config.instance.hide_objc? || Config.instance.hide_swift?
     end
     attr_accessor :file
@@ -106,6 +130,8 @@ module Jazzy
     attr_accessor :deprecation_message
     attr_accessor :unavailable
     attr_accessor :unavailable_message
+    attr_accessor :generic_requirements
+    attr_accessor :inherited_types
     def usage_discouraged?
       unavailable || deprecated
@@ -115,6 +141,36 @@ module Jazzy
       CGI.unescape(url)
     end
+    def constrained_extension?
+      type.swift_extension? &&
+        generic_requirements
+    end
+    def mark_for_children
+      if constrained_extension?
+        SourceMark.new_generic_requirements(generic_requirements)
+      else
+        SourceMark.new
+      end
+    end
+    def inherited_types?
+      inherited_types &&
+        !inherited_types.empty?
+    end
+    # 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
+    # SourceKit only sets modulename for imported modules
+    def type_from_doc_module?
+      !type.extension? ||
+        (swift? && usr && modulename.nil?)
+    end
     def alternative_abstract
       if file = alternative_abstract_file
         Pathname(file).read

data/lib/jazzy/source_declaration/type.rb CHANGED Viewed

@@ -77,6 +77,10 @@ module Jazzy
         kind == 'sourcekitten.source.lang.objc.decl.class'
       end
+      def swift_type?
+        kind.include? 'swift'
+      end
       def swift_enum_case?
         kind == 'source.lang.swift.decl.enumcase'
       end
@@ -110,6 +114,10 @@ module Jazzy
         kind == 'source.lang.swift.decl.protocol'
       end
+      def swift_typealias?
+        kind == 'source.lang.swift.decl.typealias'
+      end
       def param?
         # SourceKit strangely categorizes initializer parameters as local
         # variables, so both kinds represent a parameter in jazzy.

data/lib/jazzy/source_mark.rb CHANGED Viewed

@@ -28,6 +28,12 @@ module Jazzy
       self.name = mark_string[start_index..end_index]
     end
+    def self.new_generic_requirements(requirements)
+      marked_up = requirements.gsub(/\b([^=:]\S*)\b/, '`\1`')
+      text = "Available where #{marked_up}"
+      new(text)
+    end
     def empty?
       !name && !has_start_dash && !has_end_dash
     end
@@ -37,5 +43,10 @@ module Jazzy
       self.has_start_dash = other.has_start_dash
       self.has_end_dash = other.has_end_dash
     end
+    # Can we merge the contents of another mark into our own?
+    def can_merge?(other)
+      other.empty? || other.name == name
+    end
   end
 end

data/lib/jazzy/sourcekitten.rb CHANGED Viewed

@@ -62,10 +62,11 @@ module Jazzy
     # Group root-level docs by custom categories (if any) and type
     def self.group_docs(docs)
       custom_categories, docs = group_custom_categories(docs)
+      unlisted_prefix = Config.instance.custom_categories_unlisted_prefix
       type_categories, uncategorized = group_type_categories(
-        docs, custom_categories.any? ? 'Other ' : ''
+        docs, custom_categories.any? ? unlisted_prefix : ''
       )
-      custom_categories + type_categories + uncategorized
+      custom_categories + merge_categories(type_categories) + uncategorized
     end
     def self.group_custom_categories(docs)
@@ -98,6 +99,19 @@ module Jazzy
       [group.compact, docs]
     end
+    # Join categories with the same name (eg. ObjC and Swift classes)
+    def self.merge_categories(categories)
+      merged = []
+      categories.each do |new_category|
+        if existing = merged.find { |c| c.name == new_category.name }
+          existing.children += new_category.children
+        else
+          merged.append(new_category)
+        end
+      end
+      merged
+    end
     def self.make_group(group, name, abstract, url_name = nil)
       group.reject! { |doc| doc.name.empty? }
       unless group.empty?
@@ -111,6 +125,18 @@ module Jazzy
       end
     end
+    # Merge consecutive sections with the same mark into one section
+    def self.merge_consecutive_marks(docs)
+      prev_mark = nil
+      docs.each do |doc|
+        if prev_mark && prev_mark.can_merge?(doc.mark)
+          doc.mark = prev_mark
+        end
+        prev_mark = doc.mark
+        merge_consecutive_marks(doc.children)
+      end
+    end
     def self.sanitize_filename(doc)
       unsafe_filename = doc.url_name || doc.name
       sanitzation_enabled = Config.instance.use_safe_filenames
@@ -185,7 +211,9 @@ module Jazzy
     def self.use_spm?(options)
       options.swift_build_tool == :spm ||
         (!options.swift_build_tool_configured &&
-         Dir['*.xcodeproj'].empty?)
+         Dir['*.xcodeproj', '*.xcworkspace'].empty? &&
+         !options.build_tool_arguments.include?('-project') &&
+         !options.build_tool_arguments.include?('-workspace'))
     end
     # Builds SourceKitten arguments based on Jazzy options
@@ -195,7 +223,7 @@ module Jazzy
         arguments += objc_arguments_from_options(options)
       else
         arguments += ['--spm'] if use_spm?(options)
-        if options.module_name_configured
+        unless options.module_name.empty?
           arguments += ['--module-name', options.module_name]
         end
         arguments += ['--']
@@ -260,8 +288,13 @@ module Jazzy
     def self.should_document?(doc)
       return false if doc['key.doc.comment'].to_s.include?(':nodoc:')
+      type = SourceDeclaration::Type.new(doc['key.kind'])
       # Always document Objective-C declarations.
-      return true if Config.instance.objc_mode
+      return true unless type.swift_type?
+      # Don't document Swift types if we are hiding Swift
+      return false if Config.instance.hide_swift?
       # Don't document @available declarations with no USR, since it means
       # they're unavailable.
@@ -269,22 +302,29 @@ module Jazzy
         return false
       end
-      # Document extensions & enum elements, since we can't tell their ACL.
-      type = SourceDeclaration::Type.new(doc['key.kind'])
+      # Document enum elements, since we can't tell their ACL.
       return true if type.swift_enum_element?
-      if type.swift_extension?
-        return Array(doc['key.substructure']).any? do |subdoc|
-          subtype = SourceDeclaration::Type.new(subdoc['key.kind'])
-          !subtype.mark? && should_document?(subdoc)
-        end
-      end
+      # 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
-      acl_ok.tap { @stats.add_acl_skipped unless acl_ok }
+      unless acl_ok
+        @stats.add_acl_skipped
+        @inaccessible_protocols.append(doc['key.name']) if type.swift_protocol?
+      end
+      acl_ok
     end
     # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/PerceivedComplexity
+    def self.should_document_swift_extension?(doc)
+      doc['key.inheritedtypes'] ||
+        Array(doc['key.substructure']).any? do |subdoc|
+          subtype = SourceDeclaration::Type.new(subdoc['key.kind'])
+          !subtype.mark? && should_document?(subdoc)
+        end
+    end
     def self.should_mark_undocumented(filepath)
       source_directory = Config.instance.source_directory.to_s
       (filepath || '').start_with?(source_directory)
@@ -294,14 +334,14 @@ module Jazzy
       make_default_doc_info(declaration)
       filepath = doc['key.filepath']
-      objc = Config.instance.objc_mode
-      if objc || should_mark_undocumented(filepath)
+      if !declaration.swift? || should_mark_undocumented(filepath)
         @stats.add_undocumented(declaration)
         return nil if @skip_undocumented
         declaration.abstract = undocumented_abstract
       else
         declaration.abstract = Markdown.render(doc['key.doc.comment'] || '',
-                                               Highlighter.default_language)
+                                               declaration.highlight_language)
       end
       declaration
@@ -320,16 +360,7 @@ module Jazzy
     def self.make_doc_info(doc, declaration)
       return unless should_document?(doc)
-      if Config.instance.objc_mode
-        declaration.declaration =
-          Highlighter.highlight(doc['key.parsed_declaration'])
-        declaration.other_language_declaration =
-          Highlighter.highlight(doc['key.swift_declaration'], 'swift')
-      else
-        declaration.declaration =
-          Highlighter.highlight(make_swift_declaration(doc, declaration))
-      end
+      highlight_declaration(doc, declaration)
       make_deprecation_info(doc, declaration)
       unless doc['key.doc.full_as_xml']
@@ -337,7 +368,7 @@ module Jazzy
       end
       declaration.abstract = Markdown.render(doc['key.doc.comment'] || '',
-                                             Highlighter.default_language)
+                                             declaration.highlight_language)
       declaration.discussion = ''
       declaration.return = Markdown.rendered_returns
       declaration.parameters = parameters(doc, Markdown.rendered_parameters)
@@ -345,6 +376,18 @@ module Jazzy
       @stats.add_documented
     end
+    def self.highlight_declaration(doc, declaration)
+      if declaration.swift?
+        declaration.declaration =
+          Highlighter.highlight_swift(make_swift_declaration(doc, declaration))
+      else
+        declaration.declaration =
+          Highlighter.highlight_objc(doc['key.parsed_declaration'])
+        declaration.other_language_declaration =
+          Highlighter.highlight_swift(doc['key.swift_declaration'])
+      end
+    end
     def self.make_deprecation_info(doc, declaration)
       if declaration.deprecated
         declaration.deprecation_message =
@@ -398,9 +441,9 @@ module Jazzy
       annotated.empty? ||
         parsed &&
           (annotated.include?(' = default') || # SR-2608
-           parsed.match('@autoclosure|@escaping') || # SR-6321
-           parsed.include?("\n") ||
-           parsed.include?('extension '))
+            (parsed.scan(/@autoclosure|@escaping/).count >
+             annotated.scan(/@autoclosure|@escaping/).count) || # SR-6321
+           parsed.include?("\n"))
     end
     # Replace the fully qualified name of a type with its base name
@@ -422,6 +465,9 @@ module Jazzy
       # From source code
       parsed_decl = doc['key.parsed_declaration']
+      # Don't present type attributes on extensions
+      return parsed_decl if declaration.type.extension?
       decl =
         if prefer_parsed_decl?(parsed_decl, annotated_decl_body)
           # Strip any attrs captured by parsed version
@@ -443,14 +489,10 @@ module Jazzy
     end
     def self.make_substructure(doc, declaration)
-      declaration.children = if doc['key.substructure']
-                               make_source_declarations(
-                                 doc['key.substructure'],
-                                 declaration,
-                               )
-                             else
-                               []
-                             end
+      return [] unless subdocs = doc['key.substructure']
+      make_source_declarations(subdocs,
+                               declaration,
+                               declaration.mark_for_children)
     end
     # rubocop:disable Metrics/MethodLength
@@ -471,8 +513,7 @@ module Jazzy
         declaration.type = SourceDeclaration::Type.new(doc['key.kind'])
         declaration.typename = doc['key.typename']
         declaration.objc_name = doc['key.name']
-        documented_name = if Config.instance.hide_declarations == 'objc' &&
-                             doc['key.swift_name']
+        documented_name = if Config.instance.hide_objc? && doc['key.swift_name']
                             doc['key.swift_name']
                           else
                             declaration.objc_name
@@ -508,10 +549,17 @@ module Jazzy
         declaration.end_line = doc['key.parsed_scope.end']
         declaration.deprecated = doc['key.always_deprecated']
         declaration.unavailable = doc['key.always_unavailable']
+        declaration.generic_requirements =
+          find_generic_requirements(doc['key.parsed_declaration'])
+        inherited_types = doc['key.inheritedtypes'] || []
+        declaration.inherited_types =
+          inherited_types.map { |type| type['key.name'] }.compact
         next unless make_doc_info(doc, declaration)
-        make_substructure(doc, declaration)
-        next if declaration.type.extension? && declaration.children.empty?
+        declaration.children = make_substructure(doc, declaration)
+        next if declaration.type.extension? &&
+                declaration.children.empty? &&
+                !declaration.inherited_types?
         declarations << declaration
       end
       declarations
@@ -520,12 +568,22 @@ module Jazzy
     # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/MethodLength
+    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
     # Expands extensions of nested types declared at the top level into
     # a tree so they can be deduplicated properly
     def self.expand_extensions(decls)
       decls.map do |decl|
         next decl unless decl.type.extension? && decl.name.include?('.')
+        # Don't expand the Swift namespace if we're in ObjC mode.
+        # ex: NS_SWIFT_NAME(Foo.Bar) should not create top-level Foo
+        next decl if decl.swift_objc_extension? && !Config.instance.hide_objc?
         name_parts = decl.name.split('.')
         decl.name = name_parts.pop
         expand_extension(decl, name_parts, decls)
@@ -539,6 +597,7 @@ module Jazzy
       SourceDeclaration.new.tap do |decl|
         make_default_doc_info(decl)
         decl.name = name
+        decl.modulename = extension.modulename
         decl.type = extension.type
         decl.mark = extension.mark
         decl.usr = candidates.first.usr unless candidates.empty?
@@ -561,10 +620,10 @@ module Jazzy
                          .group_by { |d| deduplication_key(d, declarations) }
                          .values
-      duplicate_groups.map do |group|
+      duplicate_groups.flat_map do |group|
         # Put extended type (if present) before extensions
         merge_declarations(group)
-      end
+      end.compact
     end
     # Returns true if an Objective-C declaration is mergeable.
@@ -574,13 +633,28 @@ module Jazzy
             && name_match(decl.objc_category_name[0], root_decls))
     end
+    # Returns if a Swift declaration is mergeable.
+    # Start off merging in typealiases to help understand extensions.
+    def self.mergeable_swift?(decl)
+      decl.type.swift_extensible? ||
+        decl.type.swift_extension? ||
+        decl.type.swift_typealias?
+    end
     # Two declarations get merged if they have the same deduplication key.
     def self.deduplication_key(decl, root_decls)
-      if decl.type.swift_extensible? || decl.type.swift_extension?
+      # Swift extension of objc class
+      if decl.swift_objc_extension?
+        [decl.swift_extension_objc_name, :objc_class_and_categories]
+      # Swift type or Swift extension of Swift type
+      elsif mergeable_swift?(decl)
         [decl.usr, decl.name]
+      # Objc categories and classes
       elsif mergeable_objc?(decl, root_decls)
-        name, _ = decl.objc_category_name || decl.name
+        # Using the ObjC name to match swift_objc_extension.
+        name, _ = decl.objc_category_name || decl.objc_name
         [name, :objc_class_and_categories]
+      # Non-mergable declarations (funcs, typedefs etc...)
       else
         [decl.usr, decl.name, decl.type.kind]
       end
@@ -599,17 +673,36 @@ module Jazzy
       end
       typedecl = typedecls.first
+      extensions = reject_inaccessible_extensions(typedecl, extensions)
       if typedecl
         if typedecl.type.swift_protocol?
-          merge_default_implementations_into_protocol(typedecl, extensions)
-          mark_members_from_protocol_extension(extensions)
+          mark_and_merge_protocol_extensions(typedecl, extensions)
           extensions.reject! { |ext| ext.children.empty? }
         end
-        merge_declaration_marks(typedecl, extensions)
+        merge_objc_declaration_marks(typedecl, extensions)
       end
-      decls = typedecls + extensions
+      # Keep type-aliases separate from any extensions
+      if typedecl && 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/MethodLength
+    def self.merge_type_and_extensions(typedecls, extensions)
+      # Constrained extensions at the end
+      constrained, regular_exts = extensions.partition(&:constrained_extension?)
+      decls = typedecls + regular_exts + constrained
+      return nil if decls.empty?
+      move_merged_extension_marks(decls)
+      merge_code_declaration(decls)
       decls.first.tap do |merged|
         merged.children = deduplicate_declarations(
           decls.flat_map(&:children).uniq,
@@ -619,58 +712,112 @@ module Jazzy
         end
       end
     end
-    # rubocop:enable Metrics/MethodLength
+    # Now we know all the public types and all the private protocols,
+    # reject extensions that add public protocols to private types
+    # or add private protocols to public types.
+    def self.reject_inaccessible_extensions(typedecl, extensions)
+      swift_exts, objc_exts = extensions.partition(&:swift?)
+      # Reject extensions that are just conformances to private protocols
+      unwanted_exts, wanted_exts = swift_exts.partition do |ext|
+        ext.children.empty? &&
+          !ext.other_inherited_types?(@inaccessible_protocols)
+      end
+      # Given extensions of a type from this module, without the
+      # type itself, the type must be private and the extensions
+      # should be rejected.
+      if !typedecl &&
+         wanted_exts.first &&
+         wanted_exts.first.type_from_doc_module?
+        unwanted_exts += wanted_exts
+        wanted_exts = []
+      end
+      # Don't tell the user to document them
+      unwanted_exts.each { |e| @stats.remove_undocumented(e) }
+      objc_exts + wanted_exts
+    end
+    # Protocol extensions.
+    #
     # If any of the extensions provide default implementations for methods in
     # the given protocol, merge those members into the protocol doc instead of
     # keeping them on the extension. These get a “Default implementation”
-    # annotation in the generated docs.
-    def self.merge_default_implementations_into_protocol(protocol, extensions)
-      protocol.children.each do |proto_method|
-        extensions.each do |ext|
-          defaults, ext.children = ext.children.partition do |ext_member|
-            ext_member.name == proto_method.name
+    # annotation in the generated docs.  Default implementations added by
+    # conditional extensions are annotated but listed separately.
+    #
+    # Protocol methods provided only in an extension and not in the protocol
+    # itself are a special beast: they do not use dynamic dispatch. These get an
+    # “Extension method” annotation in the generated docs.
+    def self.mark_and_merge_protocol_extensions(protocol, extensions)
+      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
           end
-          unless defaults.empty?
-            proto_method.default_impl_abstract =
-              defaults.flat_map { |d| [d.abstract, d.discussion] }.join
+          # Extension-only method, keep.
+          unless proto_member
+            ext_member.from_protocol_extension = true
+            next true
+          end
+          # Default impl but constrained, mark and keep.
+          if ext.constrained_extension?
+            ext_member.default_impl_abstract = ext_member.abstract
+            ext_member.abstract = nil
+            next true
           end
+          # Default impl for all users, merge.
+          proto_member.default_impl_abstract = ext_member.abstract
+          next false
         end
       end
     end
-    # Protocol methods provided only in an extension and not in the protocol
-    # itself are a special beast: they do not use dynamic dispatch. These get an
-    # “Extension method” annotation in the generated docs.
-    def self.mark_members_from_protocol_extension(extensions)
+    # Mark children merged from categories with the name of category
+    # (unless they already have a mark)
+    def self.merge_objc_declaration_marks(typedecl, extensions)
+      return unless typedecl.type.objc_class?
       extensions.each do |ext|
-        ext.children.each do |ext_member|
-          ext_member.from_protocol_extension = true
-        end
+        _, category_name = ext.objc_category_name
+        ext.children.each { |c| c.mark.name ||= category_name }
       end
     end
-    # Customize marks associated with to-be-merged declarations
-    def self.merge_declaration_marks(typedecl, extensions)
-      if typedecl.type.objc_class?
-        # Mark children merged from categories with the name of category
-        # (unless they already have a mark)
-        extensions.each do |ext|
-          _, category_name = ext.objc_category_name
-          ext.children.each { |c| c.mark.name ||= category_name }
-        end
-      else
-        # If the Swift extension has a mark and the first child doesn't
-        # then copy the mark contents down so it still shows up.
-        extensions.each do |ext|
-          child = ext.children.first
-          if child && child.mark.empty?
-            child.mark.copy(ext.mark)
-          end
+    # 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]
+      to_be_merged.each do |ext|
+        child = ext.children.first
+        if child && child.mark.empty?
+          child.mark.copy(ext.mark)
         end
       end
     end
+    # Merge useful information added by extensions into the main
+    # declaration: public protocol conformances and, for top-level extensions,
+    # further conditional extensions of the same type.
+    def self.merge_code_declaration(decls)
+      first = decls.first
+      declarations = decls[1..-1].select do |decl|
+        decl.type.swift_extension? &&
+          (decl.other_inherited_types?(@inaccessible_protocols) ||
+            (first.type.swift_extension? && decl.constrained_extension?))
+      end.map(&:declaration)
+      unless declarations.empty?
+        first.declaration = declarations.prepend(first.declaration).uniq.join
+      end
+    end
     # Apply filtering based on the "included" and "excluded" flags.
     def self.filter_files(json)
       json = filter_included_files(json) if Config.instance.included_files.any?
@@ -826,19 +973,18 @@ module Jazzy
       @min_acl = min_acl
       @skip_undocumented = skip_undocumented
       @stats = Stats.new
-      sourcekitten_json = filter_files(JSON.parse(sourcekitten_output))
+      @inaccessible_protocols = []
+      sourcekitten_json = filter_files(JSON.parse(sourcekitten_output).flatten)
       docs = make_source_declarations(sourcekitten_json).concat inject_docs
       docs = expand_extensions(docs)
       docs = deduplicate_declarations(docs)
-      if Config.instance.objc_mode
-        docs = reject_objc_types(docs)
-      else
-        # Remove top-level enum cases because it means they have an ACL lower
-        # than min_acl
-        docs = docs.reject { |doc| doc.type.swift_enum_element? }
-      end
+      docs = reject_objc_types(docs)
+      # Remove top-level enum cases because it means they have an ACL lower
+      # than min_acl
+      docs = docs.reject { |doc| doc.type.swift_enum_element? }
       ungrouped_docs = docs
       docs = group_docs(docs)
+      merge_consecutive_marks(docs)
       make_doc_urls(docs)
       autolink(docs, ungrouped_docs)
       [docs, @stats]