RubyGems - yard - Versions diffs - 0.9.38 → 0.9.44 - Mend

yard 0.9.38 → 0.9.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +59 -1
data/LICENSE +1 -1
data/README.md +19 -22
data/docs/GettingStarted.md +41 -15
data/docs/Parser.md +17 -42
data/docs/Tags.md +26 -5
data/docs/WhatsNew.md +59 -7
data/docs/templates/default/yard_tags/html/setup.rb +1 -1
data/lib/yard/autoload.rb +18 -0
data/lib/yard/cli/diff.rb +7 -2
data/lib/yard/code_objects/proxy.rb +1 -1
data/lib/yard/handlers/processor.rb +1 -0
data/lib/yard/handlers/rbs/attribute_handler.rb +79 -0
data/lib/yard/handlers/rbs/base.rb +38 -0
data/lib/yard/handlers/rbs/constant_handler.rb +18 -0
data/lib/yard/handlers/rbs/method_handler.rb +327 -0
data/lib/yard/handlers/rbs/mixin_handler.rb +20 -0
data/lib/yard/handlers/rbs/namespace_handler.rb +26 -0
data/lib/yard/handlers/ruby/attribute_handler.rb +7 -4
data/lib/yard/handlers/ruby/constant_handler.rb +1 -0
data/lib/yard/i18n/locale.rb +1 -1
data/lib/yard/i18n/pot_generator.rb +1 -1
data/lib/yard/parser/rbs/rbs_parser.rb +325 -0
data/lib/yard/parser/rbs/statement.rb +75 -0
data/lib/yard/parser/ruby/legacy/irb/slex.rb +19 -1
data/lib/yard/parser/ruby/ruby_parser.rb +55 -3
data/lib/yard/parser/source_parser.rb +3 -2
data/lib/yard/registry_resolver.rb +7 -0
data/lib/yard/rubygems/specification.rb +1 -1
data/lib/yard/server/commands/base.rb +4 -10
data/lib/yard/server/library_version.rb +1 -1
data/lib/yard/server/static_caching.rb +36 -5
data/lib/yard/server/templates/default/fulldoc/html/css/custom.css +168 -88
data/lib/yard/server/templates/default/fulldoc/html/js/autocomplete.js +203 -12
data/lib/yard/server/templates/default/layout/html/breadcrumb.erb +1 -17
data/lib/yard/server/templates/default/method_details/html/permalink.erb +4 -2
data/lib/yard/server/templates/doc_server/library_list/html/headers.erb +3 -3
data/lib/yard/server/templates/doc_server/library_list/html/library_list.erb +2 -3
data/lib/yard/server/templates/doc_server/processing/html/processing.erb +22 -16
data/lib/yard/tags/directives.rb +7 -0
data/lib/yard/tags/library.rb +3 -3
data/lib/yard/tags/types_explainer.rb +165 -39
data/lib/yard/templates/helpers/base_helper.rb +1 -1
data/lib/yard/templates/helpers/html_helper.rb +16 -5
data/lib/yard/templates/helpers/html_syntax_highlight_helper.rb +6 -1
data/lib/yard/templates/helpers/markup/html_entities.rb +2140 -0
data/lib/yard/templates/helpers/markup/hybrid_markdown.rb +2131 -0
data/lib/yard/templates/helpers/markup_helper.rb +4 -2
data/lib/yard/version.rb +1 -1
data/po/ja.po +82 -82
data/templates/default/fulldoc/html/css/common.css +1 -1
data/templates/default/fulldoc/html/css/full_list.css +201 -53
data/templates/default/fulldoc/html/css/style.css +988 -389
data/templates/default/fulldoc/html/full_list.erb +4 -4
data/templates/default/fulldoc/html/js/app.js +801 -395
data/templates/default/fulldoc/html/js/full_list.js +332 -242
data/templates/default/layout/html/headers.erb +1 -1
data/templates/default/layout/html/layout.erb +3 -1
data/templates/default/method/html/header.erb +3 -3
data/templates/default/module/html/defines.erb +3 -3
data/templates/default/module/html/inherited_methods.erb +1 -0
data/templates/default/module/html/method_summary.erb +8 -0
data/templates/default/module/setup.rb +20 -0
data/templates/default/onefile/html/layout.erb +3 -4
data/templates/guide/fulldoc/html/css/style.css +347 -97
data/templates/guide/fulldoc/html/js/app.js +61 -33
data/templates/guide/layout/html/layout.erb +69 -72
metadata +15 -4

data/lib/yard/server/templates/doc_server/processing/html/processing.erb CHANGED Viewed

@@ -2,29 +2,35 @@
 <html>
   <head>
     <meta charset="utf-8">
-    <link rel="stylesheet" href="<%= abs_url('css', 'style.css') %>?<%= mtime('css/style.css') %>" type="text/css" media="screen" charset="utf-8" />
-    <link rel="stylesheet" href="<%= abs_url('css', 'custom.css') %>?<%= mtime('css/custom.css') %>" type="text/css" media="screen" charset="utf-8" />
-    <script type="text/javascript" charset="utf-8" src="<%= abs_url('js', 'jquery.js') %>?<%= mtime('js/jquery.js') %>"></script>
+    <link rel="stylesheet" href="<%= abs_url('css', 'style.css') %>?<%= mtime('css/style.css') %>" type="text/css" media="screen" charset="utf-8">
+    <link rel="stylesheet" href="<%= abs_url('css', 'custom.css') %>?<%= mtime('css/custom.css') %>" type="text/css" media="screen" charset="utf-8">
     <script type="text/javascript" charset="utf-8">
       function checkPage(process) {
-        $.ajax({cache: false, url: "<%= router.request.path %>" + (process ? "?process=true" : ""),
-          statusCode: { 200: function() { window.location.reload(true); } } });
-        setTimeout('checkPage()', 2000);
+        fetch("<%= router.request.path %>" + (process ? "?process=true" : ""), { cache: "no-store" })
+          .then(function(response) {
+            if (response.status === 200) window.location.reload();
+          });
+        setTimeout(checkPage, 2000);
       }
       function setFade() {
         centerMessage();
-        $(window).resize(function() { centerMessage(); });
-        $('#fade').fadeIn();
-        $('#processing').fadeIn();
+        window.addEventListener("resize", centerMessage);
+        document.getElementById('fade').style.display = 'block';
+        document.getElementById('processing').style.display = 'block';
       }
       function centerMessage() {
-        $('#fade').css('width', $(window).width() + 'px');
-        $('#fade').css('height', $(window).height() - parseInt($('#fade').css('top')) + 'px');
-        $('#processing').css('left', ($(window).width() / 2 - $('#processing').width() / 2) + 'px');
-        $('#processing').css('top', ($(window).height() / 2 - $('#processing').height() / 2) + 'px');
+        var fade = document.getElementById('fade');
+        var processing = document.getElementById('processing');
+        var fadeTop = parseInt(window.getComputedStyle(fade).top, 10) || 0;
+        fade.style.width = window.innerWidth + 'px';
+        fade.style.height = (window.innerHeight - fadeTop) + 'px';
+        processing.style.left = (window.innerWidth / 2 - processing.offsetWidth / 2) + 'px';
+        processing.style.top = (window.innerHeight / 2 - processing.offsetHeight / 2) + 'px';
       }
-      $(function() { checkPage(true); });
-      $(setFade);
+      document.addEventListener("DOMContentLoaded", function() {
+        checkPage(true);
+        setFade();
+      });
     </script>
     <style type="text/css" media="screen">
       body { overflow: hidden; margin: 12px; display: block; }
@@ -46,7 +52,7 @@
         <strong><%= @library.name %></strong> <% if @library.version %>(<%= @library.version %>)<% end %> is being processed.
         You'll be redirected when the pages are built, it shouldn't take much longer.
       </p>
-      <img src="<%= abs_url('images', 'processing.gif') %>?<%= mtime('images/processing.gif') %>" align="center" />
+      <img src="<%= abs_url('images', 'processing.gif') %>?<%= mtime('images/processing.gif') %>" align="center">
     </div>
   </body>
 </html>

data/lib/yard/tags/directives.rb CHANGED Viewed

@@ -543,6 +543,7 @@ module YARD
     # @since 0.8.0
     class ParseDirective < Directive
       def call
+        existing = YARD::Registry.all.lazy.map(&:path).to_set if handler
         lang = tag.types ? tag.types.first.to_sym :
           (handler ? handler.parser.parser_type : :ruby)
         if handler && lang == handler.parser.parser_type
@@ -555,6 +556,12 @@ module YARD
           src_parser.file = handler.parser.file if handler
           src_parser.parse(StringIO.new(tag.text))
         end
+        return unless handler
+        YARD::Registry.all.each do |obj|
+          next if existing.include? obj.path
+          obj.files.each { |entry| entry[1] = handler.statement.line if entry[0] == handler.parser.file.to_s }
+          obj.source = handler.statement.source
+        end
       end
     end

data/lib/yard/tags/library.rb CHANGED Viewed

@@ -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/types_explainer.rb CHANGED Viewed

@@ -4,6 +4,9 @@ require 'strscan'
 module YARD
   module Tags
     class TypesExplainer
+      # Regular expression to match symbol and string literals
+      LITERALMATCH = /:\w+|'[^']*'|"[^"]*"/
       # (see Tag#explain_types)
       # @param types [Array<String>] a list of types to parse and summarize
       def self.explain(*types)
@@ -31,16 +34,14 @@ module YARD
         end
         def to_s(singular = true)
-          if name[0, 1] == "#"
-            (singular ? "an object that responds to " : "objects that respond to ") + list_join(name.split(/ *& */), with: "and")
-          elsif name[0, 1] =~ /[A-Z]/
+          if name[0, 1] =~ /[A-Z]/
             singular ? "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} " + name : "#{name}#{name[-1, 1] =~ /[A-Z]/ ? "'" : ''}s"
           else
             name
           end
         end
-        private
+        protected
         def list_join(list, with: "or")
           index = 0
@@ -54,6 +55,20 @@ module YARD
         end
       end
+      # @private
+      class LiteralType < Type
+        def to_s(_singular = true)
+          "a literal value #{name}"
+        end
+      end
+      # @private
+      class DuckType < Type
+        def to_s(singular = true)
+          (singular ? "an object that responds to " : "objects that respond to ") + list_join(name.split(/ *& */), with: "and")
+        end
+      end
       # @private
       class CollectionType < Type
         attr_accessor :types
@@ -77,18 +92,56 @@ module YARD
       # @private
       class HashCollectionType < Type
-        attr_accessor :key_types, :value_types
+        attr_accessor :key_value_pairs
-        def initialize(name, key_types, value_types)
+        def initialize(name, key_types_or_pairs, value_types = nil)
           @name = name
-          @key_types = key_types
-          @value_types = value_types
+          if value_types.nil?
+            # New signature: (name, key_value_pairs)
+            @key_value_pairs = key_types_or_pairs || []
+          else
+            # Old signature: (name, key_types, value_types)
+            @key_value_pairs = [[key_types_or_pairs, value_types]]
+          end
+        end
+        # Backward compatibility accessors
+        def key_types
+          return [] if @key_value_pairs.empty?
+          @key_value_pairs.first[0] || []
+        end
+        def key_types=(types)
+          if @key_value_pairs.empty?
+            @key_value_pairs = [[types, []]]
+          else
+            @key_value_pairs[0][0] = types
+          end
+        end
+        def value_types
+          return [] if @key_value_pairs.empty?
+          @key_value_pairs.first[1] || []
+        end
+        def value_types=(types)
+          if @key_value_pairs.empty?
+            @key_value_pairs = [[[], types]]
+          else
+            @key_value_pairs[0][1] = types
+          end
         end
         def to_s(_singular = true)
-          "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} with keys made of (" +
-            list_join(key_types.map {|t| t.to_s(false) }) +
-            ") and values of (" + list_join(value_types.map {|t| t.to_s(false) }) + ")"
+          return "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name}" if @key_value_pairs.empty?
+          result = "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} with "
+          parts = @key_value_pairs.map do |keys, values|
+            "keys made of (" + list_join(keys.map {|t| t.to_s(false) }) +
+            ") and values of (" + list_join(values.map {|t| t.to_s(false) }) + ")"
+          end
+          result + parts.join(" and ")
         end
       end
@@ -101,12 +154,15 @@ module YARD
           :collection_end => />/,
           :fixed_collection_start => /\(/,
           :fixed_collection_end => /\)/,
-          :type_name => /#{ISEP}#{METHODNAMEMATCH}|#{NAMESPACEMATCH}|\w+/,
-          :type_next => /[,;]/,
+          :type_name => /#{ISEP}#{METHODNAMEMATCH}|#{NAMESPACEMATCH}|#{LITERALMATCH}|\w+/,
+          :symbol => /:#{METHODNAMEMATCH}/,
+          :type_next => /[,]/,
           :whitespace => /\s+/,
           :hash_collection_start => /\{/,
-          :hash_collection_next => /=>/,
+          :hash_collection_value => /=>/,
+          :hash_collection_value_end => /;/,
           :hash_collection_end => /\}/,
+          # :symbol_start => /:/,
           :parse_end => nil
         }
@@ -118,10 +174,45 @@ module YARD
           @scanner = StringScanner.new(string)
         end
-        def parse
-          types = []
+        # @return [Array(Boolean, Array<Type>)] - finished, types
+        def parse(until_tokens: [:parse_end])
+          current_parsed_types = []
           type = nil
           name = nil
+          finished = false
+          parse_with_handlers do |token_type, token|
+            case token_type
+            when *until_tokens
+              raise SyntaxError, "expecting name, got '#{token}'" if name.nil?
+              type = create_type(name) unless type
+              current_parsed_types << type
+              finished = true
+            when :type_name
+              raise SyntaxError, "expecting END, got name '#{token}'" if name
+              name = token
+            when :type_next
+              raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
+              type = create_type(name) unless type
+              current_parsed_types << type
+              name = nil
+              type = nil
+            when :fixed_collection_start, :collection_start
+              name ||= "Array"
+              klass = token_type == :collection_start ? CollectionType : FixedCollectionType
+              type = klass.new(name, parse(until_tokens: [:fixed_collection_end, :collection_end, :parse_end]))
+            when :hash_collection_start
+              name ||= "Hash"
+              type = parse_hash_collection(name)
+            end
+            [finished, current_parsed_types]
+          end
+        end
+        private
+        # @return [Array<Type>]
+        def parse_with_handlers
           loop do
             found = false
             TOKENS.each do |token_type, match|
@@ -129,32 +220,67 @@ module YARD
               # rubocop:disable Lint/AssignmentInCondition
               next unless (match.nil? && @scanner.eos?) || (match && token = @scanner.scan(match))
               found = true
-              case token_type
-              when :type_name
-                raise SyntaxError, "expecting END, got name '#{token}'" if name
-                name = token
-              when :type_next
-                raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
-                type = Type.new(name) unless type
-                types << type
-                type = nil
-                name = nil
-              when :fixed_collection_start, :collection_start
-                name ||= "Array"
-                klass = token_type == :collection_start ? CollectionType : FixedCollectionType
-                type = klass.new(name, parse)
-              when :hash_collection_start
-                name ||= "Hash"
-                type = HashCollectionType.new(name, parse, parse)
-              when :hash_collection_next, :hash_collection_end, :fixed_collection_end, :collection_end, :parse_end
-                raise SyntaxError, "expecting name, got '#{token}'" if name.nil?
-                type = Type.new(name) unless type
-                types << type
-                return types
-              end
+              # @type [Array<Type>]
+              finished, types = yield(token_type, token)
+              return types if finished
+              break
             end
             raise SyntaxError, "invalid character at #{@scanner.peek(1)}" unless found
           end
+          nil
+        end
+        def parse_hash_collection(name)
+          key_value_pairs = []
+          current_keys = []
+          finished = false
+          parse_with_handlers do |token_type, token|
+            case token_type
+            when :type_name
+              current_keys << create_type(token)
+            when :type_next
+              # Comma - continue collecting keys unless we just processed a value
+              # In that case, start a new key group
+            when :hash_collection_value
+              # => - current keys map to the next value(s)
+              raise SyntaxError, "no keys before =>" if current_keys.empty?
+              values = parse(until_tokens: [:hash_collection_value_end, :parse_end])
+              key_value_pairs << [current_keys, values]
+              current_keys = []
+            when :hash_collection_end, :parse_end
+              # End of hash
+              finished = true
+            when :whitespace
+              # Ignore whitespace
+            end
+            [finished, HashCollectionType.new(name, key_value_pairs)]
+          end
+        end
+        private
+        def create_type(name)
+          if name[0, 1] == ":" || (name[0, 1] =~ /['"]/ && name[-1, 1] =~ /['"]/)
+            LiteralType.new(name)
+          elsif name[0, 1] == "#"
+            DuckType.new(name)
+          else
+            Type.new(name)
+          end
+        end
+        private
+        def create_type(name)
+          if name[0, 1] == ":" || (name[0, 1] =~ /['"]/ && name[-1, 1] =~ /['"]/)
+            LiteralType.new(name)
+          elsif name[0, 1] == "#"
+            DuckType.new(name)
+          else
+            Type.new(name)
+          end
         end
       end
     end

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

@@ -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 CHANGED Viewed

@@ -93,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 table])
+          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
@@ -156,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
@@ -228,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
@@ -650,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 CHANGED Viewed

@@ -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)