yard 0.9.28 → 0.9.43

data/lib/yard/tags/library.rb

@@ -507,7 +507,7 @@ module YARD
       #
       # @example
       #   # Synchronizes system time using NTP.
-      #   # @see http://ntp.org/documentation.html NTP Documentation
+      #   # @see https://ntp.org/documentation.html NTP Documentation
       #   # @see NTPHelperMethods
       #   class NTPUpdater; end
       define_tag "See Also",           :see,         :with_name
@@ -541,7 +541,7 @@ module YARD
       # @example
       #   # @todo Add support for Jabberwocky service.
       #   #   There is an open source Jabberwocky library available
-      #   #   at http://jbrwcky.org that can be easily integrated.
+      #   #   at https://jbrwcky.org that can be easily integrated.
       #   class Wonderlander; end
       # @see tag:note
       define_tag "Todo Item",          :todo
@@ -554,7 +554,7 @@ module YARD
       # of a specific object.
       #
       # @example
-      #   # The public REST API for http://jbrwcky.org
+      #   # The public REST API for https://jbrwcky.org
       #   # @version 2.0
       #   class JabberwockyAPI; end
       define_tag "Version",            :version

data/lib/yard/tags/overload_tag.rb

@@ -60,7 +60,8 @@ module YARD
           args = YARD::Handlers::Ruby::Legacy::Base.new(nil, nil).send(:tokval_list, toks, :all)
           args = args.map do |a|
             k, v = *a.split(/:|=/, 2)
-            [k.strip.to_s + (a[k.size, 1] == ':' ? ':' : ''), (v ? v.strip : nil)]
+            v.strip! if v
+            [k.strip.to_s + (a[k.size, 1] == ':' ? ':' : ''), (v && v.empty? ? nil : v)]
           end if args
           @name = meth.to_sym
           @parameters = args

data/lib/yard/tags/tag.rb

@@ -23,6 +23,7 @@ module YARD
       attr_accessor :types
 
       # @return [String] a name associated with the tag
+      # @return [nil] if no tag name is supplied
       attr_accessor :name
 
       # @return [CodeObjects::Base] the associated object
@@ -37,7 +38,7 @@ module YARD
       # +raise+, etc.
       #
       # @param [#to_s] tag_name        the tag name to create the tag for
-      # @param [String] text           the descriptive text for this tag
+      # @param [String, nil] text      the descriptive text for this tag, or nil if none provided
       # @param [Array<String>] types   optional type list of formally declared types
       #                                for the tag
       # @param [String] name           optional key name which the tag refers to
@@ -58,10 +59,10 @@ module YARD
       end
 
       # Provides a plain English summary of the type specification, or nil
-      # if no types are provided or parseable.
+      # if no types are provided or parsable.
       #
       # @return [String] a plain English description of the associated types
-      # @return [nil] if no types are provided or not parseable
+      # @return [nil] if no types are provided or not parsable
       def explain_types
         return nil if !types || types.empty?
         TypesExplainer.explain(*types)

data/lib/yard/tags/types_explainer.rb

@@ -13,7 +13,7 @@ module YARD
       end
 
       # (see explain)
-      # @raise [SyntaxError] if the types are not parseable
+      # @raise [SyntaxError] if the types are not parsable
       def self.explain!(*types)
         Parser.parse(types.join(", ")).join("; ")
       end
@@ -32,7 +32,7 @@ module YARD
 
         def to_s(singular = true)
           if name[0, 1] == "#"
-            singular ? "an object that responds to #{name}" : "objects that respond to #{name}"
+            (singular ? "an object that responds to " : "objects that respond to ") + list_join(name.split(/ *& */), with: "and")
           elsif name[0, 1] =~ /[A-Z]/
             singular ? "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} " + name : "#{name}#{name[-1, 1] =~ /[A-Z]/ ? "'" : ''}s"
           else
@@ -42,12 +42,12 @@ module YARD
 
         private
 
-        def list_join(list)
+        def list_join(list, with: "or")
           index = 0
           list.inject(String.new) do |acc, el|
             acc << el.to_s
             acc << ", " if index < list.size - 2
-            acc << " or " if index == list.size - 2
+            acc << " #{with} " if index == list.size - 2
             index += 1
             acc
           end
@@ -102,6 +102,7 @@ module YARD
           :fixed_collection_start => /\(/,
           :fixed_collection_end => /\)/,
           :type_name => /#{ISEP}#{METHODNAMEMATCH}|#{NAMESPACEMATCH}|\w+/,
+          :symbol => /:#{METHODNAMEMATCH}/,
           :type_next => /[,;]/,
           :whitespace => /\s+/,
           :hash_collection_start => /\{/,
@@ -130,7 +131,7 @@ module YARD
               next unless (match.nil? && @scanner.eos?) || (match && token = @scanner.scan(match))
               found = true
               case token_type
-              when :type_name
+              when :type_name, :symbol
                 raise SyntaxError, "expecting END, got name '#{token}'" if name
                 name = token
               when :type_next

data/lib/yard/templates/engine.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-require 'ostruct'
 
 module YARD
   module Templates

data/lib/yard/templates/helpers/base_helper.rb

@@ -45,7 +45,7 @@ module YARD::Templates::Helpers
     # method depending on the arguments passed in.
     #
     # @example Linking a URL
-    #   linkify('http://example.com')
+    #   linkify('https://example.com')
     # @example Including docstring contents of an object
     #   linkify('include:YARD::Docstring')
     # @example Linking to an extra file

data/lib/yard/templates/helpers/html_helper.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
-require 'cgi'
+if RUBY_VERSION < '3.5'
+  require 'cgi/util'
+else
+  require 'cgi/escape'
+end
 
 module YARD
   module Templates::Helpers
@@ -89,10 +93,16 @@ module YARD
                              :tables,
                              :with_toc_data,
                              :no_intraemphasis).to_html
+        when 'Commonmarker'
+          provider.to_html(text, :options => { }, :plugins => { :syntax_highlighter => nil })
         when 'CommonMarker'
-          CommonMarker.render_html(text, %i[DEFAULT GITHUB_PRE_LANG], %i[autolink])
+          provider.render_html(text, %i[DEFAULT GITHUB_PRE_LANG], %i[autolink table])
         else
-          provider.new(text).to_html
+          if provider.respond_to?(:to_html)
+            provider.to_html(text)
+          else
+            provider.new(text).to_html
+          end
         end
       end
 
@@ -152,7 +162,7 @@ module YARD
       # @return [String] the output HTML
       # @since 0.6.0
       def html_markup_text(text)
-        h(text).gsub(/\r?\n/, '<br/>')
+        h(text).gsub(/\r?\n/, '<br>')
       end
 
       # @return [String] the same text with no markup
@@ -224,7 +234,7 @@ module YARD
       # @return [String] HTML with linkified references
       def resolve_links(text)
         code_tags = 0
-        text.gsub(%r{<(/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+</|$)}m) do |str|
+        text.gsub(%r{<(/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=\W|.+</|$)}m) do |str|
           closed = $1
           tag = $2
           escape = $3
@@ -646,7 +656,12 @@ module YARD
           language ||= detect_lang_in_codeblock_attributes($1, $2)
           language ||= object.source_type
 
-          if options.highlight
+          # Skip re-highlighting if the block is already highlighted (e.g. from a recursive
+          # htmlify call via {include:} or {yard:include_tags}). Passing pre-highlighted HTML
+          # through CGI.unescapeHTML would corrupt deliberately-escaped entities inside spans.
+          # Note: this heuristic suppresses highlighting for code blocks in :html markup that
+          # contain a literal <span> tag in the source being documented (an uncommon edge case).
+          if options.highlight && string !~ HtmlSyntaxHighlightHelper::ALREADY_HIGHLIGHTED_RE
             string = html_syntax_highlight(CGI.unescapeHTML(string), language)
           end
           classes = ['code', language].compact.join(' ')

data/lib/yard/templates/helpers/html_syntax_highlight_helper.rb

@@ -6,6 +6,11 @@ module YARD
       module HtmlSyntaxHighlightHelper
         include ModuleHelper
 
+        # Matches source that has already been highlighted (i.e. contains a span tag).
+        # Used to avoid double-processing pre-highlighted HTML in the rescue clause of
+        # {#html_syntax_highlight_ruby_ripper} and in the {HtmlHelper#parse_codeblocks} guard.
+        ALREADY_HIGHLIGHTED_RE = /<span[\s>]/
+
         # Highlights Ruby source
         # @param [String] source the Ruby source code
         # @return [String] the highlighted Ruby source
@@ -39,7 +44,7 @@ module YARD
           end
           output
         rescue Parser::ParserSyntaxError
-          source =~ /^<span\s+class=/ ? source : h(source)
+          source =~ ALREADY_HIGHLIGHTED_RE ? source : h(source)
         end
 
         def html_syntax_highlight_ruby_legacy(source)