jazzy 0.3.2 → 0.4.0

data/lib/jazzy/sourcekitten.rb

@@ -9,6 +9,8 @@ require 'jazzy/highlighter'
 require 'jazzy/source_declaration'
 require 'jazzy/source_mark'
 
+ELIDED_AUTOLINK_TOKEN = '36f8f5912051ae747ef441d6511ca4cb'.freeze
+
 module Jazzy
   # This module interacts with the sourcekitten command-line executable
   module SourceKitten
@@ -68,9 +70,9 @@ module Jazzy
         if parents.empty? || doc.children.count > 0
           # Create HTML page for this doc if it has children or is root-level
           doc.url = (
-              subdir_for_doc(doc, parents) +
-              [doc.name + '.html']
-            ).join('/')
+            subdir_for_doc(doc, parents) +
+            [doc.name + '.html']
+          ).join('/')
           doc.children = make_doc_urls(doc.children, parents + [doc])
         else
           # Don't create HTML page for this doc if it doesn't have children
@@ -111,11 +113,17 @@ module Jazzy
     # Builds SourceKitten arguments based on Jazzy options
     def self.arguments_from_options(options)
       arguments = ['doc']
-      unless options.module_name.empty?
+      if options.objc_mode
+        if options.xcodebuild_arguments.empty?
+          arguments += ['--objc', options.umbrella_header.to_s, '-x',
+                        'objective-c', '-isysroot',
+                        `xcrun --show-sdk-path`.chomp, '-I',
+                        options.framework_root.to_s]
+        end
+      elsif !options.module_name.empty?
         arguments += ['--module-name', options.module_name]
       end
-      arguments += options.xcodebuild_arguments
-      arguments
+      arguments + options.xcodebuild_arguments
     end
 
     # Run sourcekitten with given arguments and return STDOUT
@@ -125,8 +133,8 @@ module Jazzy
         raise "Unable to find an Xcode with swift version #{swift_version}."
       end
       bin_path = Pathname(__FILE__).parent + 'SourceKitten/bin/sourcekitten'
-      output, _ = Executable.execute_command(bin_path, arguments, true,
-                                             env: xcode.as_env)
+      output, = Executable.execute_command(bin_path, arguments, true,
+                                           env: xcode.as_env)
       output
     end
 
@@ -147,10 +155,13 @@ module Jazzy
     def self.should_document?(doc)
       return false if doc['key.doc.comment'].to_s.include?(':nodoc:')
 
+      # Always document Objective-C declarations.
+      return true if Config.instance.objc_mode
+
       # Document extensions & enum elements, since we can't tell their ACL.
       type = SourceDeclaration::Type.new(doc['key.kind'])
-      return true if type.enum_element?
-      if type.extension?
+      return true if type.swift_enum_element?
+      if type.swift_extension?
         return Array(doc['key.substructure']).any? do |subdoc|
           should_document?(subdoc)
         end
@@ -162,7 +173,8 @@ module Jazzy
     def self.process_undocumented_token(doc, declaration)
       source_directory = Config.instance.source_directory.to_s
       filepath = doc['key.filepath']
-      if filepath && filepath.start_with?(source_directory)
+      objc = Config.instance.objc_mode
+      if filepath && (filepath.start_with?(source_directory) || objc)
         @undocumented_tokens << doc
       end
       return nil if !documented_child?(doc) && @skip_undocumented
@@ -205,7 +217,7 @@ module Jazzy
       declaration.column = doc['key.doc.column']
       declaration.declaration = Highlighter.highlight(
         doc['key.parsed_declaration'] || doc['key.doc.declaration'],
-        'swift',
+        Config.instance.objc_mode ? 'objc' : 'swift',
       )
       declaration.abstract = comment_from_doc(doc)
       declaration.discussion = ''
@@ -251,10 +263,8 @@ module Jazzy
         declaration = SourceDeclaration.new
         declaration.type = SourceDeclaration::Type.new(doc['key.kind'])
         declaration.typename = doc['key.typename']
-        if declaration.type.mark? && doc['key.name'].start_with?('MARK: ')
-          current_mark = SourceMark.new(doc['key.name'])
-        end
-        if declaration.type.enum_case?
+        current_mark = SourceMark.new(doc['key.name']) if declaration.type.mark?
+        if declaration.type.swift_enum_case?
           # Enum "cases" are thin wrappers around enum "elements".
           declarations += make_source_declarations(doc['key.substructure'])
           next
@@ -292,11 +302,80 @@ module Jazzy
         (@undocumented_tokens.count + @documented_count)
     end
 
+    # Merges multiple extensions of the same entity into a single document.
+    #
+    # Merges extensions into the protocol/class/struct/enum they extend, if it
+    # occurs in the same project.
+    #
+    # Merges redundant declarations when documenting podspecs.
     def self.deduplicate_declarations(declarations)
-      duplicates = declarations.group_by { |d| [d.usr, d.type.kind] }.values
-      duplicates.map do |decls|
-        decls.first.tap do |d|
-          d.children = deduplicate_declarations(decls.flat_map(&:children).uniq)
+      duplicate_groups = declarations
+                         .group_by { |d| deduplication_key(d) }
+                         .values
+
+      duplicate_groups.map do |group|
+        # Put extended type (if present) before extensions
+        merge_declarations(group)
+      end
+    end
+
+    # Two declarations get merged if they have the same deduplication key.
+    def self.deduplication_key(decl)
+      if decl.type.swift_extensible? || decl.type.swift_extension?
+        [decl.usr]
+      else
+        [decl.usr, decl.type.kind]
+      end
+    end
+
+    # Merges all of the given types and extensions into a single document.
+    def self.merge_declarations(decls)
+      extensions, typedecls = decls.partition { |d| d.type.swift_extension? }
+
+      if typedecls.size > 1
+        warn 'Found conflicting type declarations with the same name, which ' \
+          'may indicate a build issue or a bug in Jazzy: ' +
+          typedecls.map { |t| "#{t.type.name.downcase} #{t.name}" }.join(', ')
+      end
+      typedecl = typedecls.first
+
+      if typedecl && typedecl.type.swift_protocol?
+        merge_default_implementations_into_protocol(typedecl, extensions)
+        mark_members_from_protocol_extension(extensions)
+        extensions.reject! { |ext| ext.children.empty? }
+      end
+
+      decls = typedecls + extensions
+      decls.first.tap do |d|
+        d.children = deduplicate_declarations(decls.flat_map(&:children).uniq)
+      end
+    end
+
+    # 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
+          end
+          unless defaults.empty?
+            proto_method.default_impl_abstract =
+              defaults.flat_map { |d| [d.abstract, d.discussion] }.join("\n\n")
+          end
+        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)
+      extensions.each do |ext|
+        ext.children.each do |ext_member|
+          ext_member.from_protocol_extension = true
         end
       end
     end
@@ -309,6 +388,47 @@ module Jazzy
       end.compact
     end
 
+    def self.names_and_urls(docs)
+      docs.flat_map do |doc|
+        # FIXME: autolink more than just top-level items.
+        [{ name: doc.name, url: doc.url }] # + names_and_urls(doc.children)
+      end
+    end
+
+    def self.autolink_text(text, data, url)
+      regex = /\b(#{data.map { |d| Regexp.escape(d[:name]) }.join('|')})\b/
+      text.gsub(regex) do
+        name = Regexp.last_match(1)
+        auto_url = data.find { |d| d[:name] == name }[:url]
+        if auto_url == url # docs shouldn't autolink to themselves
+          Regexp.last_match(0)
+        else
+          "<a href=\"#{ELIDED_AUTOLINK_TOKEN}#{auto_url}\">#{name}</a>"
+        end
+      end
+    end
+
+    def self.autolink(docs, data)
+      docs.map do |doc|
+        doc.abstract = autolink_text(doc.abstract, data, doc.url)
+        doc.return = autolink_text(doc.return, data, doc.url) if doc.return
+        doc.children = autolink(doc.children, data)
+        doc
+      end
+    end
+
+    def self.reject_objc_enum_typedefs(docs)
+      enums = docs.flat_map do |doc|
+        doc.children.select { |child| child.type.objc_enum? }.map(&:name)
+      end
+      docs.map do |doc|
+        doc.children.reject! do |child|
+          child.type.objc_typedef? && enums.include?(child.name)
+        end
+        doc
+      end
+    end
+
     # Parse sourcekitten STDOUT output as JSON
     # @return [Hash] structured docs
     def self.parse(sourcekitten_output, min_acl, skip_undocumented)
@@ -318,10 +438,16 @@ module Jazzy
       docs = make_source_declarations(sourcekitten_json)
       docs = deduplicate_declarations(docs)
       docs = group_docs(docs)
-      # Remove top-level enum cases because it means they have an ACL lower
-      # than min_acl
-      docs = docs.reject { |doc| doc.type.enum_element? }
-      [make_doc_urls(docs, []), doc_coverage, @undocumented_tokens]
+      if Config.instance.objc_mode
+        docs = reject_objc_enum_typedefs(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 = make_doc_urls(docs, [])
+      docs = autolink(docs, names_and_urls(docs.flat_map(&:children)))
+      [docs, doc_coverage, @undocumented_tokens]
     end
   end
 end

data/lib/jazzy/templates/doc.mustache

@@ -10,7 +10,7 @@
   </head>
   <body>
     {{#dash_type}}
-    <a name="//apple_ref/swift/{{dash_type}}/{{name}}" class="dashAnchor"></a>
+    <a name="//apple_ref/{{language_stub}}/{{dash_type}}/{{name}}" class="dashAnchor"></a>
     {{/dash_type}}
     <a title="{{name}} {{kind}} Reference"></a>
     {{> header}}
@@ -29,7 +29,7 @@
             {{^hide_name}}<h1>{{name}}</h1>{{/hide_name}}
             {{#declaration}}
               <div class="declaration">
-                <div class="Swift">
+                <div class="language">
                   {{{declaration}}}
                 </div>
               </div>

data/lib/jazzy/templates/nav.mustache

@@ -2,7 +2,7 @@
   <ul class="nav-groups">
     {{#structure}}
     <li class="nav-group-name">
-    <a href="{{path_to_root}}{{section}}.html">{{section}}</a>
+      <a href="{{path_to_root}}{{section}}.html">{{section}}</a>
       <ul class="nav-group-tasks">
         {{#children}}
         <li class="nav-group-task">

data/lib/jazzy/templates/task.mustache

@@ -1,12 +1,12 @@
 <div class="task-group">
   {{#name}}
-    <div class="task-name-container">
-      <a name="/{{uid}}"></a>
-      <a name="//apple_ref/swift/Section/{{name}}" class="dashAnchor"></a>
-      <a href="#/{{uid}}">
-        <h3 class="section-name">{{name}}</h3>
-      </a>
-    </div>
+  <div class="task-name-container">
+    <a name="/{{uid}}"></a>
+    <a name="//apple_ref/{{language_stub}}/Section/{{name}}" class="dashAnchor"></a>
+    <a href="#/{{uid}}">
+      <h3 class="section-name">{{name}}</h3>
+    </a>
+  </div>
   {{/name}}
   <ul>
     {{#items}}
@@ -14,9 +14,19 @@
       <div>
         <code>
         <a name="/{{usr}}"></a>
-        <a name="//apple_ref/swift/{{dash_type}}/{{name}}" class="dashAnchor"></a>
+        <a name="//apple_ref/{{language_stub}}/{{dash_type}}/{{name}}" class="dashAnchor"></a>
         <a class="token" href="#/{{usr}}">{{name}}</a>
         </code>
+        {{#default_impl_abstract}}
+          <span class="declaration-note">
+            Default implementation
+          </span>
+        {{/default_impl_abstract}}
+        {{#from_protocol_extension}}
+          <span class="declaration-note">
+            Extension method
+          </span>
+        {{/from_protocol_extension}}
       </div>
       <div class="height-container">
         <div class="pointer-container"></div>
@@ -30,11 +40,17 @@
             {{/url}}
           </div>
           {{/abstract}}
+          {{#default_impl_abstract}}
+          <h4>Default Implementation</h4>
+          <div class="default_impl abstract">
+            {{{default_impl_abstract}}}
+          </div>
+          {{/default_impl_abstract}}
           {{#declaration}}
           <div class="declaration">
             <h4>Declaration</h4>
-            <div class="Swift">
-              <p class="aside-title">Swift</p>
+            <div class="language">
+              <p class="aside-title">{{language}}</p>
               {{{declaration}}}
             </div>
           </div>

data/spec/integration_spec.rb

@@ -59,7 +59,7 @@ CLIntegracon.configure do |c|
   # Ignore certain OSX files
   c.ignores '.DS_Store'
   c.ignores '.git'
-  c.ignores /^(?!(docs\/|execution_output.txt))/
+  c.ignores %r{^(?!(docs/|execution_output.txt))}
   c.ignores '*.tgz'
 
   # Transform produced databases to csv
@@ -75,7 +75,6 @@ CLIntegracon.configure do |c|
 end
 
 describe_cli 'jazzy' do
-
   subject do |s|
     s.executable = "ruby #{ROOT + 'bin/jazzy'}"
     s.environment_vars = {
@@ -105,36 +104,13 @@ describe_cli 'jazzy' do
                             '--swift-version=1.2'
     end
 
-    describe 'Creates Realm Swift docs' do
-      realm_version = ''
-      dir = ROOT + 'spec/integration_specs/document_realm_swift1.2/before'
-      Dir.chdir(dir) do
-        realm_version = `./build.sh get-version`.chomp
-        `REALM_SWIFT_VERSION=1.2 ./build.sh set-swift-version`
-      end
-      behaves_like cli_spec 'document_realm_swift1.2',
-                            '--author Realm ' \
-                            '--author_url "https://realm.io" ' \
-                            '--github_url ' \
-                            'https://github.com/realm/realm-cocoa ' \
-                            '--github-file-prefix https://github.com/realm/' \
-                            "realm-cocoa/tree/v#{realm_version} " \
-                            '--module RealmSwift ' \
-                            "--module-version #{realm_version} " \
-                            '--root-url https://realm.io/docs/swift/' \
-                            "#{realm_version}/api/ " \
-                            '--xcodebuild-arguments ' \
-                            '-project,RealmSwift.xcodeproj,-dry-run ' \
-                            '--swift-version=1.2'
-    end
-
     describe 'Creates docs for a podspec with dependencies and subspecs' do
       behaves_like cli_spec 'document_moya_podspec',
                             '--podspec=Moya.podspec --swift-version=1.2'
     end
   end if !travis_swift || travis_swift == '1.2'
 
-  describe 'jazzy swift 2.0' do
+  describe 'jazzy swift 2.1' do
     describe 'Creates docs with a module name, author name, project URL, ' \
       'xcodebuild options, and github info' do
       behaves_like cli_spec 'document_alamofire',
@@ -143,8 +119,8 @@ describe_cli 'jazzy' do
                             '-x -project,Alamofire.xcodeproj,-dry-run ' \
                             '-g https://github.com/Alamofire/Alamofire ' \
                             '--github-file-prefix https://github.com/' \
-                            'Alamofire/Alamofire/blob/swift-2.0 ' \
-                            '--module-version swift-2.0 ' \
+                            'Alamofire/Alamofire/blob/3.1.1 ' \
+                            '--module-version 3.1.1 ' \
                             '-r http://static.realm.io/jazzy_demo/Alamofire/ ' \
                             '--skip-undocumented'
     end
@@ -153,7 +129,7 @@ describe_cli 'jazzy' do
       realm_version = ''
       Dir.chdir(ROOT + 'spec/integration_specs/document_realm_swift/before') do
         realm_version = `./build.sh get-version`.chomp
-        `REALM_SWIFT_VERSION=2.0 ./build.sh set-swift-version`
+        `REALM_SWIFT_VERSION=2.1 ./build.sh set-swift-version`
       end
       behaves_like cli_spec 'document_realm_swift',
                             '--author Realm ' \
@@ -167,18 +143,37 @@ describe_cli 'jazzy' do
                             '--root-url https://realm.io/docs/swift/' \
                             "#{realm_version}/api/ " \
                             '--xcodebuild-arguments ' \
-                            '-project,RealmSwift.xcodeproj,-dry-run ' \
-                            '--template-directory "docs/templates/swift" '
+                            '-scheme,RealmSwift ' \
+                            '--template-directory docs/templates'
+    end
+
+    describe 'Creates Realm Objective-C docs' do
+      realm_version = ''
+      relative_path = 'spec/integration_specs/document_realm_objc/before'
+      Dir.chdir(ROOT + relative_path) do
+        realm_version = `./build.sh get-version`.chomp
+        # jazzy will fail if it can't find all public header files
+        `touch Realm/RLMPlatform.h`
+      end
+      behaves_like cli_spec 'document_realm_objc',
+                            '--objc ' \
+                            '--author Realm ' \
+                            '--author_url "https://realm.io" ' \
+                            '--github_url ' \
+                            'https://github.com/realm/realm-cocoa ' \
+                            '--github-file-prefix https://github.com/realm/' \
+                            "realm-cocoa/tree/v#{realm_version} " \
+                            '--module Realm ' \
+                            "--module-version #{realm_version} " \
+                            '--root-url https://realm.io/docs/objc/' \
+                            "#{realm_version}/api/ " \
+                            '--umbrella-header Realm/Realm.h ' \
+                            '--framework-root . ' \
+                            '--template-directory docs/templates'
     end
 
     describe 'Creates docs for Swift project with a variety of contents' do
-      behaves_like cli_spec 'misc_jazzy_features',
-                            '-m MiscJazzyFeatures -a Realm ' \
-                            '-u https://github.com/realm/jazzy ' \
-                            '-g https://github.com/realm/jazzy ' \
-                            '-x -dry-run ' \
-                            '--min-acl private ' \
-                            '--hide-documentation-coverage'
+      behaves_like cli_spec 'misc_jazzy_features', '-x -dry-run'
     end
-  end if !travis_swift || travis_swift == '2.0'
+  end if !travis_swift || travis_swift == '2.1'
 end