jazzy 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc460519a4f57d266ecc60cbc931be6206c3d619
-  data.tar.gz: ee27a31724d4c8740edf0060ea1f0395a75c34cd
+  metadata.gz: a26b03c9b41e98642beb50df0f4dd95c04675d00
+  data.tar.gz: ca8d320c44e4697c6e672c1087688b2d20559d70
 SHA512:
-  metadata.gz: 72ae7b9ea2eebf2dd6d7a487453cb81e33bbcebece34c63c94fe61117dda83853acbb05d74d346c331026fb0362487cf874d4fbc98d896840b4f7e84b8b26957
-  data.tar.gz: 9a6a51fe79fa42185ae16375f0560c9e471c07e59dad504663db53ab9ee1d7b748e9971f7da5ddd3bba9b6365e1ca62925a36add31e1da3b89204e8b7c3a0df8
+  metadata.gz: 045aeac969e8626b7488561dc366c89ba2449ac0e0c328f08f2a2c2fca26b185c1e898cc4689c1815fee4967ed272c5a424eabdaf5a2b2c2b0e0b476b481f744
+  data.tar.gz: 6e9aacf6d1447d50e4a025caeee2fa0879720a8c096ff7faa99c886e8e5be8995ae60d512fe4f3810140a288d6cbd8e37cc1864b5eeeba8d38d733d380d48f07

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.8.1
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Allow all markdown in returns and parameter description callouts.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#476](https://github.com/realm/jazzy/issues/476)
+
+##### Bug Fixes
+
+* Fix a crash that occurred when a documentation comment ended with an extended
+  grapheme cluster.  
+  [Lukas Stührk](https://github.com/Lukas-Stuehrk)
+  [#794](https://github.com/realm/jazzy/issues/794)
+  [SourceKitten#350](https://github.com/jpsim/SourceKitten/issues/350)
+
 ## 0.8.0
 
 ##### Breaking

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.8.0)
+    jazzy (0.8.1)
       cocoapods (~> 1.0)
       mustache (~> 0.99)
       open4

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Commandant.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>16C53a</string>
+	<string>16E195</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.11.3</string>
+	<string>0.12.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleSupportedPlatforms</key>
@@ -29,17 +29,17 @@
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>16B2649</string>
+	<string>16E185</string>
 	<key>DTSDKName</key>
 	<string>macosx10.12</string>
 	<key>DTXcode</key>
-	<string>0810</string>
+	<string>0832</string>
 	<key>DTXcodeBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2014 Carthage. All rights reserved.</string>
 </dict>

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Result.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>16C53a</string>
+	<string>16E195</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>3.1.0</string>
+	<string>3.2.1</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleSupportedPlatforms</key>
@@ -29,17 +29,17 @@
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>16B2649</string>
+	<string>16E185</string>
 	<key>DTSDKName</key>
 	<string>macosx10.12</string>
 	<key>DTXcode</key>
-	<string>0810</string>
+	<string>0832</string>
 	<key>DTXcodeBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2015 Rob Rix. All rights reserved.</string>
 </dict>

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>16C53a</string>
+	<string>16E195</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -29,17 +29,17 @@
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>16B2649</string>
+	<string>16E185</string>
 	<key>DTSDKName</key>
 	<string>macosx10.12</string>
 	<key>DTXcode</key>
-	<string>0810</string>
+	<string>0832</string>
 	<key>DTXcodeBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>UIDeviceFamily</key>
 	<array>
 		<integer>1</integer>

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Yams.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>16C53a</string>
+	<string>16E195</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.1.2</string>
+	<string>0.3.1</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleSupportedPlatforms</key>
@@ -25,20 +25,20 @@
 		<string>MacOSX</string>
 	</array>
 	<key>CFBundleVersion</key>
-	<string></string>
+	<string>1</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>16B2649</string>
+	<string>16E185</string>
 	<key>DTSDKName</key>
 	<string>macosx10.12</string>
 	<key>DTXcode</key>
-	<string>0810</string>
+	<string>0832</string>
 	<key>DTXcodeBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 </dict>
 </plist>

data/lib/jazzy/SourceKitten/Frameworks/SourceKittenFramework.framework/Versions/A/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>16C53a</string>
+	<string>16E195</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.15.2</string>
+	<string>0.17.2</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleSupportedPlatforms</key>
@@ -29,17 +29,17 @@
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>DTPlatformVersion</key>
 	<string>GM</string>
 	<key>DTSDKBuild</key>
-	<string>16B2649</string>
+	<string>16E185</string>
 	<key>DTSDKName</key>
 	<string>macosx10.12</string>
 	<key>DTXcode</key>
-	<string>0810</string>
+	<string>0832</string>
 	<key>DTXcodeBuild</key>
-	<string>8B62</string>
+	<string>8E2002</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2015 SourceKitten. All rights reserved.</string>
 </dict>

data/lib/jazzy/doc.rb

@@ -19,7 +19,7 @@ module Jazzy
         "© #{year} [#{config.author_name}](#{config.author_url}). " \
         "All rights reserved. (Last updated: #{date})"
       )
-      Jazzy.copyright_markdown.render(copyright).chomp
+      Markdown.render_copyright(copyright).chomp
     end
 
     def jazzy_version

data/lib/jazzy/doc_builder.rb

@@ -220,7 +220,7 @@ module Jazzy
       doc = Doc.new # Mustache model instance
       name = doc_model.name == 'index' ? source_module.name : doc_model.name
       doc[:name] = name
-      doc[:overview] = Jazzy.markdown.render(doc_model.content(source_module))
+      doc[:overview] = Markdown.render(doc_model.content(source_module))
       doc[:custom_head] = Config.instance.custom_head
       doc[:disable_search] = Config.instance.disable_search
       doc[:doc_coverage] = source_module.doc_coverage unless
@@ -366,7 +366,7 @@ module Jazzy
       overview = (doc_model.abstract || '') + (doc_model.discussion || '')
       alternative_abstract = doc_model.alternative_abstract
       if alternative_abstract
-        overview = Jazzy.markdown.render(alternative_abstract) + overview
+        overview = Markdown.render(alternative_abstract) + overview
       end
 
       doc = Doc.new # Mustache model instance

data/lib/jazzy/gem_version.rb

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

data/lib/jazzy/jazzy_markdown.rb

@@ -3,99 +3,102 @@ require 'rouge'
 require 'rouge/plugins/redcarpet'
 
 module Jazzy
-  class JazzyHTML < Redcarpet::Render::HTML
-    include Redcarpet::Render::SmartyPants
-    include Rouge::Plugins::Redcarpet
-
-    def header(text, header_level)
-      text_slug = text.gsub(/[^\w]+/, '-')
-                      .downcase
-                      .sub(/^-/, '')
-                      .sub(/-$/, '')
-
-      "<h#{header_level} id='#{text_slug}' class='heading'>" \
-        "#{text}" \
-      "</h#{header_level}>\n"
-    end
+  module Markdown
+    class JazzyHTML < Redcarpet::Render::HTML
+      include Redcarpet::Render::SmartyPants
+      include Rouge::Plugins::Redcarpet
+
+      def header(text, header_level)
+        text_slug = text.gsub(/[^\w]+/, '-')
+                        .downcase
+                        .sub(/^-/, '')
+                        .sub(/-$/, '')
+
+        "<h#{header_level} id='#{text_slug}' class='heading'>" \
+          "#{text}" \
+        "</h#{header_level}>\n"
+      end
+
+      # List from
+      # https://github.com/apple/swift/blob/master/include/swift/Markup/SimpleFields.def
+      UNIQUELY_HANDLED_CALLOUTS = %w(parameters
+                                     parameter
+                                     returns).freeze
+      GENERAL_CALLOUTS = %w(attention
+                            author
+                            authors
+                            bug
+                            complexity
+                            copyright
+                            date
+                            experiment
+                            important
+                            invariant
+                            keyword
+                            mutatingvariant
+                            nonmutatingvariant
+                            note
+                            postcondition
+                            precondition
+                            recommended
+                            recommendedover
+                            remark
+                            remarks
+                            requires
+                            see
+                            seealso
+                            since
+                            todo
+                            throws
+                            version
+                            warning).freeze
+      SPECIAL_LIST_TYPES = (UNIQUELY_HANDLED_CALLOUTS + GENERAL_CALLOUTS).freeze
+
+      SPECIAL_LIST_TYPE_REGEX = %r{
+        \A\s* # optional leading spaces
+        (<p>\s*)? # optional opening p tag
+        # any one of our special list types
+        (#{SPECIAL_LIST_TYPES.map(&Regexp.method(:escape)).join('|')})
+        [\s:] # followed by either a space or a colon
+      }ix
 
-    # List from
-    # https://github.com/apple/swift/blob/master/include/swift/Markup/SimpleFields.def
-    UNIQUELY_HANDLED_CALLOUTS = %w(parameters
-                                   parameter
-                                   returns).freeze
-    GENERAL_CALLOUTS = %w(attention
-                          author
-                          authors
-                          bug
-                          complexity
-                          copyright
-                          date
-                          experiment
-                          important
-                          invariant
-                          keyword
-                          mutatingvariant
-                          nonmutatingvariant
-                          note
-                          postcondition
-                          precondition
-                          recommended
-                          recommendedover
-                          remark
-                          remarks
-                          requires
-                          see
-                          seealso
-                          since
-                          todo
-                          throws
-                          version
-                          warning).freeze
-    SPECIAL_LIST_TYPES = (UNIQUELY_HANDLED_CALLOUTS + GENERAL_CALLOUTS).freeze
-
-    SPECIAL_LIST_TYPE_REGEX = %r{
-      \A\s* # optional leading spaces
-      (<p>\s*)? # optional opening p tag
-      # any one of our special list types
-      (#{SPECIAL_LIST_TYPES.map(&Regexp.method(:escape)).join('|')})
-      [\s:] # followed by either a space or a colon
-    }ix
-
-    ELIDED_LI_TOKEN = '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'.freeze
-
-    def list_item(text, _list_type)
-      if text =~ SPECIAL_LIST_TYPE_REGEX
-        type = Regexp.last_match(2)
-        if UNIQUELY_HANDLED_CALLOUTS.include? type.downcase
-          return ELIDED_LI_TOKEN
+      ELIDED_LI_TOKEN =
+        '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'.freeze
+
+      def list_item(text, _list_type)
+        if text =~ SPECIAL_LIST_TYPE_REGEX
+          type = Regexp.last_match(2)
+          if UNIQUELY_HANDLED_CALLOUTS.include? type.downcase
+            return ELIDED_LI_TOKEN
+          end
+          return render_aside(type, text.sub(/#{Regexp.escape(type)}:\s+/, ''))
         end
-        return render_aside(type, text.sub(/#{Regexp.escape(type)}:\s+/, ''))
+        str = '<li>'
+        str << text.strip
+        str << "</li>\n"
       end
-      str = '<li>'
-      str << text.strip
-      str << "</li>\n"
-    end
 
-    def render_aside(type, text)
-      <<-HTML
+      def render_aside(type, text)
+        <<-HTML
 <div class="aside aside-#{type.underscore.tr('_', '-')}">
     <p class="aside-title">#{type.underscore.humanize}</p>
     #{text}
 </div>
-      HTML
-    end
+        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")
+      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")
+      end
     end
 
-    OPTIONS = {
+    REDCARPET_OPTIONS = {
       autolink: true,
       fenced_code_blocks: true,
       no_intra_emphasis: true,
@@ -105,23 +108,87 @@ module Jazzy
       tables: true,
       lax_spacing: true,
     }.freeze
-  end
 
-  def self.markdown
-    @markdown ||= Redcarpet::Markdown.new(JazzyHTML, JazzyHTML::OPTIONS)
-  end
+    # Spot and capture returns & param HTML for separate display.
+    class JazzyDeclarationHTML < JazzyHTML
+      attr_reader :returns, :parameters
+
+      def reset
+        @returns = nil
+        @parameters = {}
+      end
+
+      INTRO_PAT = '\A(?<intro>\s*(<p>\s*)?)'.freeze
+      OUTRO_PAT = '(?<outro>.*)\z'.freeze
+
+      RETURNS_REGEX = /#{INTRO_PAT}returns:#{OUTRO_PAT}/im
+
+      IDENT_PAT = '(?<param>\S+)'.freeze
+
+      # Param formats: normal swift, objc via sourcekitten, and
+      # possibly inside 'Parameters:'
+      PARAM_PAT1 = "(parameter +#{IDENT_PAT}\\s*:)".freeze
+      PARAM_PAT2 = "(parameter:\\s*#{IDENT_PAT}\\s+)".freeze
+      PARAM_PAT3 = "(#{IDENT_PAT}\\s*:)".freeze
+
+      PARAM_PAT = "(?:#{PARAM_PAT1}|#{PARAM_PAT2}|#{PARAM_PAT3})".freeze
+
+      PARAM_REGEX = /#{INTRO_PAT}#{PARAM_PAT}#{OUTRO_PAT}/im
 
-  class JazzyCopyright < Redcarpet::Render::HTML
-    def link(link, _title, content)
-      %(<a class="link" href="#{link}" target="_blank" \
+      def list_item(text, _list_type)
+        if text =~ RETURNS_REGEX
+          @returns = render_param_returns(Regexp.last_match)
+        elsif text =~ PARAM_REGEX
+          @parameters[Regexp.last_match(:param)] =
+            render_param_returns(Regexp.last_match)
+        end
+        super
+      end
+
+      def render_param_returns(matches)
+        body = matches[:intro].strip + matches[:outro].strip
+        body = "<p>#{body}</p>" unless body.start_with?('<p>')
+        Redcarpet::Render::SmartyPants.render(body)
+      end
+    end
+
+    def self.renderer
+      @renderer ||= JazzyDeclarationHTML.new
+    end
+
+    def self.markdown
+      @markdown ||= Redcarpet::Markdown.new(renderer, REDCARPET_OPTIONS)
+    end
+
+    def self.render(markdown_text)
+      renderer.reset
+      markdown.render(markdown_text)
+    end
+
+    def self.rendered_returns
+      renderer.returns
+    end
+
+    def self.rendered_parameters
+      renderer.parameters
+    end
+
+    class JazzyCopyright < Redcarpet::Render::HTML
+      def link(link, _title, content)
+        %(<a class="link" href="#{link}" target="_blank" \
 rel="external">#{content}</a>)
+      end
     end
-  end
 
-  def self.copyright_markdown
-    @copyright_markdown ||= Redcarpet::Markdown.new(
-      JazzyCopyright,
-      JazzyHTML::OPTIONS,
-    )
+    def self.copyright_markdown
+      @copyright_markdown ||= Redcarpet::Markdown.new(
+        JazzyCopyright,
+        REDCARPET_OPTIONS,
+      )
+    end
+
+    def self.render_copyright(markdown_text)
+      copyright_markdown.render(markdown_text)
+    end
   end
 end

data/lib/jazzy/sourcekitten.rb

@@ -48,7 +48,7 @@ module Jazzy
   module SourceKitten
     @documented_count = 0
     @undocumented_decls = []
-    @default_abstract = Jazzy.markdown.render('Undocumented').freeze
+    @default_abstract = Markdown.render('Undocumented').freeze
 
     # Group root-level docs by custom categories (if any) and type
     def self.group_docs(docs)
@@ -94,7 +94,7 @@ module Jazzy
         SourceDeclaration.new.tap do |sd|
           sd.type     = SourceDeclaration::Type.overview
           sd.name     = name
-          sd.abstract = Jazzy.markdown.render(abstract)
+          sd.abstract = Markdown.render(abstract)
           sd.children = group
         end
       end
@@ -284,28 +284,12 @@ module Jazzy
       make_default_doc_info(declaration)
     end
 
-    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 code = p['Verbatim'] || p['CodeListing']
-          Jazzy.markdown.render("```\n#{code}```\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)
+    def self.parameters(doc, discovered)
       (doc['key.doc.parameters'] || []).map do |p|
+        name = p['name']
         {
-          name: p['name'],
-          discussion: make_paragraphs(p, 'discussion'),
+          name: name,
+          discussion: discovered[name],
         }
       end
     end
@@ -329,11 +313,10 @@ module Jazzy
         )
       end
 
-      declaration.abstract = Jazzy.markdown.render(doc['key.doc.comment'] || '')
+      declaration.abstract = Markdown.render(doc['key.doc.comment'] || '')
       declaration.discussion = ''
-      declaration.return = make_paragraphs(doc, 'key.doc.result_discussion')
-
-      declaration.parameters = parameters(doc)
+      declaration.return = Markdown.rendered_returns
+      declaration.parameters = parameters(doc, Markdown.rendered_parameters)
 
       @documented_count += 1
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazzy
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - JP Simard
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-27 00:00:00.000000000 Z
+date: 2017-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocoapods