Merge pull request #209 from realm/no-xml

[SourceKitten] use SourceKitten's XML parsing

Gemfile.lock

@@ -2,10 +2,8 @@ PATH
   remote: .
   specs:
     jazzy (0.1.4)
-      activesupport (~> 4.1)
       cocoapods (~> 0.36.0.rc.1)
       mustache (~> 0.99)
-      nokogiri (~> 1.6)
       open4
       redcarpet (~> 3.2)
       rouge (~> 1.5)
@@ -64,7 +62,6 @@ GEM
     i18n (0.7.0)
     json (1.8.2)
     metaclass (0.0.4)
-    mini_portile (0.6.2)
     minitest (5.5.1)
     mocha (1.1.0)
       metaclass (~> 0.0.1)
@@ -74,8 +71,6 @@ GEM
     mustache (0.99.8)
     nap (0.8.0)
     netrc (0.7.8)
-    nokogiri (1.6.6.2)
-      mini_portile (~> 0.6.0)
     open4 (1.3.4)
     parser (2.2.0.pre.5)
       ast (>= 1.1, < 3.0)

jazzy.gemspec

@@ -19,10 +19,8 @@ Gem::Specification.new do |spec|
 
   spec.extensions    = ['lib/jazzy/SourceKitten/Rakefile']
 
-  spec.add_runtime_dependency 'activesupport', '~> 4.1'
   spec.add_runtime_dependency 'cocoapods', '~> 0.36.0.rc.1'
   spec.add_runtime_dependency 'mustache', '~> 0.99'
-  spec.add_runtime_dependency 'nokogiri', '~> 1.6'
   spec.add_runtime_dependency 'open4'
   spec.add_runtime_dependency 'redcarpet', '~> 3.2'
   spec.add_runtime_dependency 'rouge', '~> 1.5'

lib/jazzy/assets/css/jazzy.css.scss

@@ -89,7 +89,7 @@ pre, code {
 }
 p code, li code {
   background-color: $code_bg_color;
-  padding: 4px;
+  padding: 2px 4px;
   border-radius: 4px;
 }
 
@@ -236,19 +236,29 @@ header {
   p {
     line-height: 1.8em;
   }
-  section .section :first-child {
-    margin-top: 0;
-    padding-top: 0;
+  section {
+    .section:first-child {
+      margin-top: 0;
+      padding-top: 0;
+    }
+
+    .task-group-section .task-group:first-of-type {
+      padding-top: 10px;
+
+      .section-name {
+        padding-top: 15px;
+      }
+    }
   }
 }
 
 .section {
-  padding: 25px 25px 0;
+  padding: 0 25px;
 }
 
 .highlight {
   background-color: $code_bg_color;
-  padding: 7px;
+  padding: 10px 12px;
   border: $gray_border;
   border-radius: 4px;
   overflow-x: auto;
@@ -280,7 +290,7 @@ header {
 }
 
 .task-group {
-  padding-top: 10px;
+  padding-top: 0px;
 }
 
 .item {

lib/jazzy/sourcekitten.rb

@@ -6,7 +6,6 @@
 require 'jazzy/highlighter'
 require 'jazzy/source_declaration'
 require 'jazzy/source_mark'
-require 'jazzy/xml_helper'
 
 module Jazzy
   # This module interacts with the sourcekitten command-line executable
@@ -96,13 +95,12 @@ def self.make_default_doc_info(declaration)
 
     def self.documented_child?(doc)
       return false unless doc['key.substructure']
-      doc['key.substructure'].each do |child|
-        return true if documented_child?(child)
-      end
-      false
+      doc['key.substructure'].any? { |child| documented_child?(child) }
     end
 
     def self.should_document?(doc)
+      return false if doc['key.doc.comment'].to_s.include?(':nodoc:')
+
       # Always document extensions, since we can't tell what ACL they are
       return true if doc['key.kind'] == 'source.lang.swift.decl.extension'
 
@@ -120,41 +118,62 @@ def self.process_undocumented_token(doc, declaration)
       make_default_doc_info(declaration)
     end
 
-    def self.parameters_from_xml(xml)
-      xml.xpath('Parameters/Parameter').map do |parameter_el|
+    def self.make_paragraphs(doc, key)
+      return nil unless doc[key]
+      doc[key].map do |p|
+        if para = p['Para']
+          Jazzy.markdown.render(para)
+        elsif verbatim = p['Verbatim']
+          Jazzy.markdown.render("```\n#{verbatim}```\n")
+        else
+          warn "Jazzy could not recognize the `#{p.keys.first}` tag. " \
+               'Please report this by filing an issue at ' \
+               'https://github.com/realm/jazzy/issues along with the comment ' \
+               'including this tag.'
+          Jazzy.markdown.render(p.values.first)
+        end
+      end.join
+    end
+
+    def self.parameters(doc)
+      (doc['key.doc.parameters'] || []).map do |p|
         {
-          name: XMLHelper.xpath(parameter_el, 'Name'),
-          discussion: Jazzy.markdown.render(
-              XMLHelper.xpath(parameter_el, 'Discussion') || '',
-            ),
+          name: p['name'],
+          discussion: make_paragraphs(p, 'discussion'),
         }
       end
     end
 
     def self.make_doc_info(doc, declaration)
-      return nil unless should_document?(doc)
-      xml_key = 'key.doc.full_as_xml'
-      return process_undocumented_token(doc, declaration) unless doc[xml_key]
+      return unless should_document?(doc)
+      unless doc['key.doc.full_as_xml']
+        return process_undocumented_token(doc, declaration)
+      end
 
-      xml = Nokogiri::XML(doc[xml_key]).root
-      declaration.line = XMLHelper.attribute(xml, 'line').to_i
-      declaration.column = XMLHelper.attribute(xml, 'column').to_i
+      declaration.line = doc['key.doc.line']
+      declaration.column = doc['key.doc.column']
       declaration.declaration = Highlighter.highlight(
-        doc['key.parsed_declaration'] || XMLHelper.xpath(xml, 'Declaration'),
+        doc['key.parsed_declaration'] || doc['key.doc.declaration'],
         'swift',
       )
-      declaration.abstract = XMLHelper.xpath(xml, 'Abstract')
-      declaration.discussion = XMLHelper.xpath(xml, 'Discussion')
-      declaration.return = XMLHelper.xpath(xml, 'ResultDiscussion')
-
-      nodoc = ->(string) { string.to_s.include? '<dt>nodoc</dt>' }
-      return if nodoc[declaration.abstract] || nodoc[declaration.discussion]
+      stripped_comment = string_until_first_rest_definition(
+        doc['key.doc.comment'],
+      ) || ''
+      declaration.abstract = Jazzy.markdown.render(stripped_comment)
+      declaration.discussion = ''
+      declaration.return = make_paragraphs(doc, 'key.doc.result_discussion')
 
-      declaration.parameters = parameters_from_xml(xml)
+      declaration.parameters = parameters(doc)
 
       @documented_count += 1
     end
 
+    def self.string_until_first_rest_definition(string)
+      matches = /^\s*:[^\s]+:/.match(string)
+      return string unless matches
+      string[0...matches.begin(0)]
+    end
+
     def self.make_substructure(doc, declaration)
       if doc['key.substructure']
         declaration.children = make_source_declarations(