jazzy 0.0.13 → 0.0.14

data/lib/jazzy/config.rb

@@ -1,4 +1,5 @@
 require 'optparse'
+require 'pathname'
 
 module Jazzy
   class Config
@@ -14,7 +15,7 @@ module Jazzy
     attr_accessor :clean
 
     def initialize
-      self.output = File.expand_path('docs')
+      self.output = Pathname('docs')
       self.xcodebuild_arguments = []
       self.author_name = ''
       self.module_name = ''
@@ -26,6 +27,7 @@ module Jazzy
       self.clean = false
     end
 
+    # rubocop:disable Metrics/MethodLength
     def self.parse!
       config = new
       OptionParser.new do |opt|
@@ -33,46 +35,58 @@ module Jazzy
         opt.separator ''
         opt.separator 'Options'
 
-        opt.on('-o', '--output FOLDER', 'Folder to output the HTML docs to') do |output|
-          config.output = File.expand_path(output)
+        opt.on('-o', '--output FOLDER',
+               'Folder to output the HTML docs to') do |output|
+          config.output = Pathname(output)
         end
 
         opt.on('-c', '--[no-]clean',
                'Delete contents of output directory before running.',
-               'WARNING: If --output is set to ~/Desktop, this will delete the ~/Desktop directory.') do |clean|
+               'WARNING: If --output is set to ~/Desktop, this will delete the \
+                ~/Desktop directory.') do |clean|
           config.clean = clean
         end
 
-        opt.on('-x', '--xcodebuild-arguments arg1,arg2,…argN', Array, 'Arguments to forward to xcodebuild') do |args|
+        opt.on('-x', '--xcodebuild-arguments arg1,arg2,…argN', Array,
+               'Arguments to forward to xcodebuild') do |args|
           config.xcodebuild_arguments = args
         end
 
-        opt.on('-a', '--author AUTHOR_NAME', 'Name of author to attribute in docs (i.e. Realm)') do |a|
+        opt.on('-a', '--author AUTHOR_NAME',
+               'Name of author to attribute in docs (i.e. Realm)') do |a|
           config.author_name = a
         end
 
-        opt.on('-u', '--author_url URL', 'Author URL of this project (i.e. http://realm.io)') do |u|
+        opt.on('-u', '--author_url URL',
+               'Author URL of this project (i.e. http://realm.io)') do |u|
           config.author_url = u
         end
 
-        opt.on('-m', '--module MODULE_NAME', 'Name of module being documented. (i.e. RealmSwift)') do |m|
+        opt.on('-m', '--module MODULE_NAME',
+               'Name of module being documented. (i.e. RealmSwift)') do |m|
           config.module_name = m
         end
 
-        opt.on('-d', '--dash_url URL', 'URL to install docs in Dash (i.e. dash-feed://http%3A%2F%2Fcocoadocs.org%2Fdocsets%2FRealm%2FRealm.xml') do |d|
+        opt.on('-d', '--dash_url URL',
+               'URL to install docs in Dash (i.e. dash-feed://...') do |d|
           config.dash_url = d
         end
 
-        opt.on('-g', '--github_url URL', 'GitHub URL of this project (i.e. https://github.com/realm/realm-cocoa)') do |g|
+        opt.on('-g', '--github_url URL',
+               'GitHub URL of this project (i.e. \
+                https://github.com/realm/realm-cocoa)') do |g|
           config.github_url = g
         end
 
-        opt.on('--github-file-prefix PREFIX', 'GitHub URL file prefix of this project (i.e. https://github.com/realm/realm-cocoa/tree/v0.87.1)') do |g|
+        opt.on('--github-file-prefix PREFIX',
+               'GitHub URL file prefix of this project (i.e. \
+                https://github.com/realm/realm-cocoa/tree/v0.87.1)') do |g|
           config.github_file_prefix = g
         end
 
-        opt.on('-s', '--sourcekitten-sourcefile FILEPATH', 'XML doc file generated from sourcekitten to parse') do |s|
-          config.sourcekitten_sourcefile = s
+        opt.on('-s', '--sourcekitten-sourcefile FILEPATH',
+               'XML doc file generated from sourcekitten to parse') do |s|
+          config.sourcekitten_sourcefile = Pathname(s)
         end
 
         opt.on('-v', '--version', 'Print version number') do

data/lib/jazzy/doc.mustache

@@ -11,7 +11,7 @@
     <a title="{{name}} {{kind}} Reference"></a>
     <header>
       <div class="content-wrapper">
-        <p class="header-text"><a href="#">{{module_name}} Docs</a></p>
+        <p class="header-text"><a href="{{path_to_root}}index.html">{{module_name}} Docs</a> ({{doc_coverage}}% documented)</p>
         {{#github_url}}
         <p id="header-links"><a href="{{github_url}}"><img id="header-icon" src="{{path_to_root}}img/gh.png" height="16px" width="16px" />View on GitHub</a></p>
         {{/github_url}}
@@ -23,7 +23,7 @@
     <section id="valence">
       <div class="content-wrapper">
         <p id="hierarchial_navigation">
-        <a href="#" id="design_resources_link">{{module_name}} Reference</a>
+        <a href="{{path_to_root}}index.html" id="design_resources_link">{{module_name}} Reference</a>
         <img id="carat" src="{{path_to_root}}img/carat.png" height="10px" width="6px" />
         {{name}} {{kind}} Reference
         </p>

data/lib/jazzy/doc.rb

@@ -1,10 +1,11 @@
 require 'date'
+require 'pathname'
 
 require 'jazzy/gem_version'
 
 module Jazzy
   class Doc < Mustache
-    self.template_path = File.dirname(__FILE__) + '/..'
+    self.template_path = Pathname(__FILE__).parent.parent
 
     def date
       # Fake date is used to keep integration tests consistent

data/lib/jazzy/doc_builder.rb

@@ -1,11 +1,14 @@
 require 'fileutils'
 require 'mustache'
 require 'uri'
+require 'pathname'
+require 'sass'
 
 require 'jazzy/config'
 require 'jazzy/doc'
 require 'jazzy/jazzy_markdown'
 require 'jazzy/source_declaration'
+require 'jazzy/source_module'
 require 'jazzy/sourcekitten'
 
 module Jazzy
@@ -14,18 +17,21 @@ module Jazzy
   module DocBuilder
     # mkdir -p output directory and clean if option is set
     def self.prepare_output_dir(output_dir, clean)
-      FileUtils.rm_r output_dir if clean && File.directory?(output_dir)
+      FileUtils.rm_r output_dir if clean && output_dir.directory?
       FileUtils.mkdir_p output_dir
     end
 
     # Generate doc structure to be used in sidebar navigation
-    # @return [Array] doc structure comprised of section names and child names and URLs
+    # @return [Array] doc structure comprised of
+    #                     section names & child names & URLs
     def self.doc_structure_for_docs(docs)
       structure = []
       docs.each do |doc|
         structure << {
           section: doc.name,
-          children: doc.children.map { |child| { name: child.name, url: child.url } },
+          children: doc.children.map do |child|
+            { name: child.name, url: child.url }
+          end,
         }
       end
       structure
@@ -35,9 +41,7 @@ module Jazzy
     # @param [Config] options
     def self.build(options)
       if options.sourcekitten_sourcefile
-        file = File.open(options.sourcekitten_sourcefile)
-        file_contents = file.read
-        file.close
+        file_contents = options.sourcekitten_sourcefile.read
         build_docs_for_sourcekitten_output(file_contents, options)
       else
         stdout = SourceKitten.run_sourcekitten(options.xcodebuild_arguments)
@@ -61,16 +65,22 @@ module Jazzy
     # @param [Integer] depth Number of parents. Used to calculate path_to_root
     #        for web.
     # @param [Array] doc_structure @see #doc_structure_for_docs
-    def self.build_docs(output_dir, docs, options, depth, doc_structure)
+    def self.build_docs(output_dir, docs, source_module, depth)
       docs.each do |doc|
         next if doc.name != 'index' && doc.children.count == 0
         prepare_output_dir(output_dir, false)
-        path = File.join(output_dir, "#{doc.name}.html")
+        path = output_dir + "#{doc.name}.html"
         path_to_root = ['../'].cycle(depth).to_a.join('')
-        File.open(path, 'w') { |file| file.write(DocBuilder.document(options, doc, path_to_root, doc_structure)) }
-        if doc.name != 'index'
-          DocBuilder.build_docs(File.join(output_dir, doc.name), doc.children, options, depth + 1, doc_structure)
+        path.open('w') do |file|
+          file.write(document(source_module, doc, path_to_root))
         end
+        next if doc.name == 'index'
+        build_docs(
+          output_dir + doc.name,
+          doc.children,
+          source_module,
+          depth + 1,
+        )
       end
     end
 
@@ -80,88 +90,132 @@ module Jazzy
     def self.build_docs_for_sourcekitten_output(sourcekitten_output, options)
       output_dir = options.output
       prepare_output_dir(output_dir, options.clean)
-      docs = SourceKitten.parse(sourcekitten_output)
-      doc_structure = doc_structure_for_docs(docs)
+
+      (docs, coverage) = SourceKitten.parse(sourcekitten_output)
+
+      structure = doc_structure_for_docs(docs)
+
       docs << SourceDeclaration.new.tap { |sd| sd.name = 'index' }
-      DocBuilder.build_docs(output_dir, docs, options, 0, doc_structure)
 
-      # Copy assets into output directory
-      assets_dir = File.expand_path(File.dirname(__FILE__) + '/../../lib/jazzy/assets/') + '/.'
-      FileUtils.cp_r(assets_dir, output_dir)
+      source_module = SourceModule.new(options, docs, structure, coverage)
+      build_docs(output_dir, source_module.docs, source_module, 0)
+
+      copy_assets(output_dir)
 
-      puts 'jam out ♪♫ to your fresh new docs at ' + output_dir
+      puts "jam out ♪♫ to your fresh new docs in `#{output_dir}`"
     end
 
-    # Build Mustache document from single parsed doc
+    def self.copy_assets(destination)
+      origin = Pathname(__FILE__).parent + '../../lib/jazzy/assets/.'
+      FileUtils.cp_r(origin, destination)
+      Pathname.glob(destination + 'css/**/*.scss').each do |scss|
+        contents = scss.read
+        css = Sass::Engine.new(contents, syntax: :scss).render
+        css_filename = scss.sub(/\.scss$/, '')
+        css_filename.open('w') { |f| f.write(css) }
+        FileUtils.rm scss
+      end
+    end
+
+    # Build index Mustache document
     # @param [Config] options Build options
-    # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
     # @param [String] path_to_root
     # @param [Array] doc_structure doc structure comprised of section names and
     #        child names and URLs. @see doc_structure_for_docs
-    def self.document(options, doc_model, path_to_root, doc_structure)
+    def self.document_index(source_module, path_to_root)
       doc = Doc.new # Mustache model instance
-      # Do something special for index.
-      # @todo render README here
-      if doc_model.name == 'index'
-        doc[:name] = options.module_name
-        doc[:overview] = Jazzy.markdown.render(
-          "This is the index page for #{options.module_name} docs. " \
-          'Navigate using the links on the left.',
-        )
-        doc[:structure] = doc_structure
-        doc[:module_name] = options.module_name
-        doc[:author_name] = options.author_name
-        doc[:author_website] = options.author_url
-        doc[:github_url] = options.github_url
-        doc[:dash_url] = options.dash_url
-        doc[:path_to_root] = path_to_root
-        return doc.render
+      doc[:name] = source_module.name
+      doc[:overview] = Jazzy.markdown.render(
+        "This is the index page for #{source_module.name} docs. " \
+        'Navigate using the links on the left.',
+      )
+      doc[:doc_coverage] = source_module.doc_coverage
+      doc[:structure] = source_module.doc_structure
+      doc[:module_name] = source_module.name
+      doc[:author_name] = source_module.author_name
+      doc[:author_website] = source_module.author_url
+      doc[:github_url] = source_module.github_url
+      doc[:dash_url] = source_module.dash_url
+      doc[:path_to_root] = path_to_root
+      doc.render
+    end
+
+    # Construct Github token URL
+    # @param [Hash] item Parsed doc child item
+    # @param [Config] options Build options
+    def self.gh_token_url(item, source_module)
+      if source_module.github_file_prefix && item.file
+        gh_prefix = source_module.github_file_prefix
+        relative_file_path = item.file.gsub(`pwd`.strip, '')
+        gh_line = "#L#{item.line}"
+        gh_prefix + relative_file_path + gh_line
       end
+    end
 
-      ########################################################
-      # Map doc_model values to mustache model values
-      ########################################################
+    # Build mustache item for a top-level doc
+    # @param [Hash] item Parsed doc child item
+    # @param [Config] options Build options
+    def self.render_item(item, source_module)
+      # Combine abstract and discussion into abstract
+      abstract = (item.abstract || '') + (item.discussion || '')
+      item_render = {
+        name: item.name,
+        abstract: Jazzy.markdown.render(abstract),
+        declaration: item.declaration,
+        usr: item.usr,
+      }
+      gh_token_url = gh_token_url(item, source_module)
+      item_render[:github_token_url] = gh_token_url if gh_token_url
+      item_render[:return] = Jazzy.markdown.render(item.return) if item.return
+      item_render[:parameters] = item.parameters if item.parameters.length > 0
+      item_render
+    end
 
-      doc[:name] = doc_model.name
-      doc[:kind] = doc_model.kindName
-      doc[:overview] = Jazzy.markdown.render(doc_model.abstract || '')
-      doc[:tasks] = []
-      doc[:structure] = doc_structure
+    # Render tasks for Mustache document
+    # @param [Config] options Build options
+    # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
+    def self.render_tasks(source_module, doc_model)
+      tasks = []
       # @todo parse mark-style comments and use as task names
       tasknames = ['Children']
       tasknames.each do |taskname|
         items = []
-        doc_model.children.each do |sub_item|
-          # Combine abstract and discussion into abstract
-          abstract = (sub_item.abstract || '') + (sub_item.discussion || '')
-          item = {
-            name: sub_item.name,
-            abstract: Jazzy.markdown.render(abstract),
-            declaration: sub_item.declaration,
-            usr: sub_item.usr,
-          }
-          if options.github_file_prefix && sub_item.file
-            gh_prefix = options.github_file_prefix
-            relative_file_path = sub_item.file.gsub(`pwd`.strip, '')
-            gh_line = "#L#{sub_item.line}"
-            item[:github_token_url] = gh_prefix + relative_file_path + gh_line
-          end
-          item[:return] = Jazzy.markdown.render(sub_item.return) if sub_item.return
-          parameters = sub_item.parameters
-          item[:parameters] = parameters if parameters.length > 0
-          items << item
+        doc_model.children.each do |item|
+          items << render_item(item, source_module)
         end
-        doc[:tasks] << {
+        tasks << {
           name: '',
           uid: URI.encode(taskname),
           items: items,
         }
       end
-      doc[:module_name] = options.module_name
-      doc[:author_name] = options.author_name
-      doc[:author_website] = options.author_url
-      doc[:github_url] = options.github_url
-      doc[:dash_url] = options.dash_url
+      tasks
+    end
+
+    # Build Mustache document from single parsed doc
+    # @param [Config] options Build options
+    # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
+    # @param [String] path_to_root
+    # @param [Array] doc_structure doc structure comprised of section names and
+    #        child names and URLs. @see doc_structure_for_docs
+    def self.document(source_module, doc_model, path_to_root)
+      # @todo render README here
+      if doc_model.name == 'index'
+        return document_index(source_module, path_to_root)
+      end
+
+      doc = Doc.new # Mustache model instance
+      doc[:doc_coverage] = source_module.doc_coverage
+      doc[:name] = doc_model.name
+      doc[:kind] = doc_model.kindName
+      doc[:overview] = Jazzy.markdown.render(doc_model.abstract || '')
+      doc[:structure] = source_module.doc_structure
+      doc[:tasks] = render_tasks(source_module, doc_model)
+      doc[:module_name] = source_module.name
+      doc[:author_name] = source_module.author_name
+      doc[:author_website] = source_module.author_url
+      doc[:github_url] = source_module.github_url
+      doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc.render
     end

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.0.13' unless defined? Jazzy::VERSION
+  VERSION = '0.0.14' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/source_module.rb

@@ -0,0 +1,28 @@
+require 'jazzy/config'
+require 'jazzy/source_declaration'
+
+module Jazzy
+  class SourceModule
+    attr_accessor :name
+    attr_accessor :docs
+    attr_accessor :doc_coverage
+    attr_accessor :doc_structure
+    attr_accessor :author_name
+    attr_accessor :github_url
+    attr_accessor :github_file_prefix
+    attr_accessor :author_url
+    attr_accessor :dash_url
+
+    def initialize(options, docs, doc_structure, doc_coverage)
+      self.docs = docs
+      self.doc_structure = doc_structure
+      self.doc_coverage = doc_coverage
+      self.name = options.module_name
+      self.author_name = options.author_name
+      self.github_url = options.github_url
+      self.github_file_prefix = options.github_file_prefix
+      self.author_url = options.author_url
+      self.dash_url = options.dash_url
+    end
+  end
+end

data/lib/jazzy/sourcekitten.rb

@@ -1,5 +1,6 @@
 require 'active_support/inflector'
 require 'json'
+require 'pathname'
 
 require 'jazzy/config'
 require 'jazzy/source_declaration'
@@ -8,42 +9,40 @@ require 'jazzy/xml_helper'
 module Jazzy
   # This module interacts with the sourcekitten command-line executable
   module SourceKitten
-    # SourceKit-provided token kinds along with their human-readable descriptions
+    # SourceKit-provided token kinds along with their names
     # @todo Make sure this list is exhaustive for source.lang.swift.decl.*
-    def self.kinds
-      {
-        'source.lang.swift.decl.function.method.class' => 'Class Method',
-        'source.lang.swift.decl.var.class' => 'Class Variable',
-        'source.lang.swift.decl.class' => 'Class',
-        'source.lang.swift.decl.function.constructor' => 'Constructor',
-        'source.lang.swift.decl.function.destructor' => 'Destructor',
-        'source.lang.swift.decl.var.global' => 'Global Variable',
-        'source.lang.swift.decl.enumelement' => 'Enum Element',
-        'source.lang.swift.decl.enum' => 'Enum',
-        'source.lang.swift.decl.extension' => 'Extension',
-        'source.lang.swift.decl.function.free' => 'Function',
-        'source.lang.swift.decl.function.method.instance' => 'Instance Method',
-        'source.lang.swift.decl.var.instance' => 'Instance Variable',
-        'source.lang.swift.decl.var.local' => 'Local Variable',
-        'source.lang.swift.decl.var.parameter' => 'Parameter',
-        'source.lang.swift.decl.protocol' => 'Protocol',
-        'source.lang.swift.decl.function.method.static' => 'Static Method',
-        'source.lang.swift.decl.var.static' => 'Static Variable',
-        'source.lang.swift.decl.struct' => 'Struct',
-        'source.lang.swift.decl.function.subscript' => 'Subscript',
-        'source.lang.swift.decl.typealias' => 'Typealias',
-      }
-    end
+    @kinds = {
+      'source.lang.swift.decl.function.method.class' => 'Class Method',
+      'source.lang.swift.decl.var.class' => 'Class Variable',
+      'source.lang.swift.decl.class' => 'Class',
+      'source.lang.swift.decl.function.constructor' => 'Constructor',
+      'source.lang.swift.decl.function.destructor' => 'Destructor',
+      'source.lang.swift.decl.var.global' => 'Global Variable',
+      'source.lang.swift.decl.enumelement' => 'Enum Element',
+      'source.lang.swift.decl.enum' => 'Enum',
+      'source.lang.swift.decl.extension' => 'Extension',
+      'source.lang.swift.decl.function.free' => 'Function',
+      'source.lang.swift.decl.function.method.instance' => 'Instance Method',
+      'source.lang.swift.decl.var.instance' => 'Instance Variable',
+      'source.lang.swift.decl.var.local' => 'Local Variable',
+      'source.lang.swift.decl.var.parameter' => 'Parameter',
+      'source.lang.swift.decl.protocol' => 'Protocol',
+      'source.lang.swift.decl.function.method.static' => 'Static Method',
+      'source.lang.swift.decl.var.static' => 'Static Variable',
+      'source.lang.swift.decl.struct' => 'Struct',
+      'source.lang.swift.decl.function.subscript' => 'Subscript',
+      'source.lang.swift.decl.typealias' => 'Typealias',
+    }.freeze
 
     # Group root-level docs by kind and add as children to a group doc element
     def self.group_docs(docs, kind)
-      kind_name_plural = kinds[kind].pluralize
+      kind_name_plural = @kinds[kind].pluralize
       group, docs = docs.partition { |doc| doc.kind == kind }
       docs << SourceDeclaration.new.tap do |sd|
         sd.name = kind_name_plural
         sd.kind = 'Overview'
-        sd.abstract = "The following #{kind_name_plural.downcase} are available " \
-          'globally.'
+        sd.abstract = "The following #{kind_name_plural.downcase} are " \
+                      'available globally.'
         sd.children = group
       end if group.count > 0
       docs
@@ -69,10 +68,53 @@ module Jazzy
 
     # Run sourcekitten with given arguments and return STDOUT
     def self.run_sourcekitten(arguments)
-      bin_path = File.expand_path(File.join(File.dirname(__FILE__), '../../bin'))
+      bin_path = Pathname(__FILE__).parent + '../../bin'
       `#{bin_path}/sourcekitten #{(arguments).join(' ')}`
     end
 
+    def self.make_default_doc_info(declaration)
+      # @todo: Fix these
+      declaration.line = 0
+      declaration.column = 0
+      declaration.abstract = 'Undocumented'
+      declaration.parameters = []
+    end
+
+    def self.make_doc_info(doc, declaration)
+      if doc['key.doc.full_as_xml']
+        xml = Nokogiri::XML(doc['key.doc.full_as_xml']).root
+        declaration.line = XMLHelper.attribute(xml, 'line').to_i
+        declaration.column = XMLHelper.attribute(xml, 'column').to_i
+        declaration.declaration = XMLHelper.xpath(xml, 'Declaration')
+        declaration.abstract = XMLHelper.xpath(xml, 'Abstract')
+        declaration.discussion = XMLHelper.xpath(xml, 'Discussion')
+        declaration.return = XMLHelper.xpath(xml, 'ResultDiscussion')
+
+        declaration.parameters = []
+        xml.xpath('Parameters/Parameter').each do |parameter_el|
+          declaration.parameters << {
+            name: XMLHelper.xpath(parameter_el, 'Name'),
+            discussion: Jazzy.markdown.render(
+                XMLHelper.xpath(parameter_el, 'Discussion'),
+              ),
+          }
+        end
+      else
+        make_default_doc_info(declaration)
+      end
+    end
+
+    def self.make_substructure(doc, declaration)
+      if doc['key.substructure']
+        declaration.children = make_source_declarations(
+          doc['key.substructure'],
+        )
+      else
+        declaration.children = []
+      end
+    end
+
+    # rubocop:disable Metrics/MethodLength
     def self.make_source_declarations(docs)
       declarations = []
       docs.each do |doc|
@@ -83,63 +125,46 @@ module Jazzy
         declaration = SourceDeclaration.new
         declaration.kind = doc['key.kind']
         next unless declaration.kind =~ /^source\.lang\.swift\.decl\..*/
-        next if declaration.kind == 'source.lang.swift.decl.var.parameter'
 
-        declaration.kindName = kinds[declaration.kind]
-
-        raise 'Please file an issue on https://github.com/realm/jazzy/issues ' \
-          "about adding support for `#{declaration.kind}`" unless declaration.kindName
+        unless declaration.kindName = @kinds[declaration.kind]
+          raise 'Please file an issue on ' \
+          'https://github.com/realm/jazzy/issues about adding support for ' \
+          "`#{declaration.kind}`"
+        end
 
         declaration.kindNamePlural = declaration.kindName.pluralize
         declaration.file = doc['key.filepath']
         declaration.usr = doc['key.usr']
         declaration.name = doc['key.name']
 
-        if doc['key.doc.full_as_xml']
-          xml = Nokogiri::XML(doc['key.doc.full_as_xml']).root
-          declaration.line = XMLHelper.attribute(xml, 'line').to_i
-          declaration.column = XMLHelper.attribute(xml, 'column').to_i
-          declaration.declaration = XMLHelper.xpath(xml, 'Declaration')
-          declaration.abstract = XMLHelper.xpath(xml, 'Abstract')
-          declaration.discussion = XMLHelper.xpath(xml, 'Discussion')
-          declaration.return = XMLHelper.xpath(xml, 'ResultDiscussion')
-
-          parameters = []
-          xml.xpath('Parameters/Parameter').each do |parameter_el|
-            parameters << {
-              name: XMLHelper.xpath(parameter_el, 'Name'),
-              discussion: Jazzy.markdown.render(
-                  XMLHelper.xpath(parameter_el, 'Discussion'),
-                ),
-            }
-          end
-          declaration.parameters = parameters
-        else
-          # @todo: Fix these
-          declaration.line = 0
-          declaration.column = 0
-          declaration.abstract = 'Undocumented'
-          declaration.parameters = []
-        end
-
-        if doc['key.substructure']
-          declaration.children = make_source_declarations(doc['key.substructure'])
-        else
-          declaration.children = []
-        end
+        make_doc_info(doc, declaration)
+        make_substructure(doc, declaration)
         declarations << declaration
       end
       declarations
     end
+    # rubocop:enable Metrics/MethodLength
+
+    def self.doc_coverage(sourcekitten_json)
+      documented = sourcekitten_json
+                    .map { |el| el['key.doc.documented'] }
+                    .inject(:+)
+      undocumented = sourcekitten_json
+                      .map { |el| el['key.doc.undocumented'] }
+                      .inject(:+)
+      return 0 if documented == 0 && undocumented == 0
+      (100 * documented) / (undocumented + documented)
+    end
 
-    # Parse sourcekitten STDOUT+STDERR output as JSON
+    # Parse sourcekitten STDOUT output as JSON
     # @return [Hash] structured docs
     def self.parse(sourcekitten_output)
-      docs = make_source_declarations(JSON.parse(sourcekitten_output))
-      kinds.keys.each do |kind|
+      sourcekitten_json = JSON.parse(sourcekitten_output)
+      docs = make_source_declarations(sourcekitten_json)
+      @kinds.keys.each do |kind|
         docs = group_docs(docs, kind)
       end
-      make_doc_urls(docs, [])
+      [make_doc_urls(docs, []), doc_coverage(sourcekitten_json)]
     end
   end
 end