jazzy 0.10.0 → 0.13.0

data/lib/jazzy/source_mark.rb

@@ -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

@@ -65,7 +65,7 @@ module Jazzy
       type_categories, uncategorized = group_type_categories(
         docs, custom_categories.any? ? 'Other ' : ''
       )
-      custom_categories + type_categories + uncategorized
+      custom_categories + merge_categories(type_categories) + uncategorized
     end
 
     def self.group_custom_categories(docs)
@@ -98,6 +98,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 +124,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
@@ -126,12 +151,11 @@ module Jazzy
     # @return [Hash] input docs with URLs
     def self.make_doc_urls(docs)
       docs.each do |doc|
-        if !doc.parent_in_docs || doc.children.count > 0
-          # Create HTML page for this doc if it has children or is root-level
+        if doc.render_as_page?
           doc.url = (
             subdir_for_doc(doc) +
             [sanitize_filename(doc) + '.html']
-          ).join('/')
+          ).map { |path| ERB::Util.url_encode(path) }.join('/')
           doc.children = make_doc_urls(doc.children)
         else
           # Don't create HTML page for this doc if it doesn't have children
@@ -140,8 +164,8 @@ module Jazzy
             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 ' \
-                 "#{Config.instance.xcodebuild_arguments.shelljoin}`."
+                 '`xcodebuild` or `swift build` with arguments ' \
+                 "`#{Config.instance.build_tool_arguments.shelljoin}`."
           end
           id = doc.usr
           unless id
@@ -159,17 +183,17 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
 
-    # Determine the subdirectory in which a doc should be placed
+    # Determine the subdirectory in which a doc should be placed.
+    # Guides in the root for back-compatibility.
+    # Declarations under outer namespace type (Structures, Classes, etc.)
     def self.subdir_for_doc(doc)
-      # We always want to create top-level subdirs according to type (Struct,
-      # Class, etc).
+      return [] if doc.type.markdown?
       top_level_decl = doc.namespace_path.first
-      if top_level_decl && top_level_decl.type && top_level_decl.type.name
-        # File program elements under top ancestor’s type (Struct, Class, etc.)
+      if top_level_decl.type.name
         [top_level_decl.type.plural_url_name] +
           doc.namespace_ancestors.map(&:name)
       else
-        # Categories live in their own directory
+        # Category - in the root
         []
       end
     end
@@ -183,22 +207,33 @@ module Jazzy
       end.select { |x| x }.flatten(1)
     end
 
+    def self.use_spm?(options)
+      options.swift_build_tool == :spm ||
+        (!options.swift_build_tool_configured &&
+         Dir['*.xcodeproj', '*.xcworkspace'].empty? &&
+         !options.build_tool_arguments.include?('-project') &&
+         !options.build_tool_arguments.include?('-workspace'))
+    end
+
     # Builds SourceKitten arguments based on Jazzy options
     def self.arguments_from_options(options)
       arguments = ['doc']
-      arguments += if options.objc_mode
-                     objc_arguments_from_options(options)
-                   elsif !options.module_name.empty?
-                     ['--module-name', options.module_name, '--']
-                   else
-                     ['--']
-                   end
-      arguments + options.xcodebuild_arguments
+      if options.objc_mode
+        arguments += objc_arguments_from_options(options)
+      else
+        arguments += ['--spm'] if use_spm?(options)
+        unless options.module_name.empty?
+          arguments += ['--module-name', options.module_name]
+        end
+        arguments += ['--']
+      end
+
+      arguments + options.build_tool_arguments
     end
 
     def self.objc_arguments_from_options(options)
       arguments = []
-      if options.xcodebuild_arguments.empty?
+      if options.build_tool_arguments.empty?
         arguments += ['--objc', options.umbrella_header.to_s, '--', '-x',
                       'objective-c', '-isysroot',
                       `xcrun --show-sdk-path --sdk #{options.sdk}`.chomp,
@@ -252,8 +287,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.
@@ -261,22 +301,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)
@@ -286,14 +333,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
@@ -312,16 +359,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']
@@ -329,7 +367,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)
@@ -337,6 +375,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 =
@@ -391,8 +441,7 @@ module Jazzy
         parsed &&
           (annotated.include?(' = default') || # SR-2608
            parsed.match('@autoclosure|@escaping') || # SR-6321
-           parsed.include?("\n") ||
-           parsed.include?('extension '))
+           parsed.include?("\n"))
     end
 
     # Replace the fully qualified name of a type with its base name
@@ -414,6 +463,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
@@ -435,14 +487,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
@@ -463,8 +511,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
@@ -500,10 +547,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
@@ -512,12 +566,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)
@@ -531,6 +595,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?
@@ -553,10 +618,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.
@@ -566,13 +631,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
@@ -591,17 +671,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,
@@ -611,58 +710,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
+
+          # Extension-only method, keep.
+          unless proto_member
+            ext_member.from_protocol_extension = true
+            next true
           end
-          unless defaults.empty?
-            proto_method.default_impl_abstract =
-              defaults.flat_map { |d| [d.abstract, d.discussion] }.join
+
+          # 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?
@@ -818,19 +971,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]