yard 0.9.36 → 0.9.38

data/lib/yard/parser/ruby/ast_node.rb

@@ -271,7 +271,7 @@ module YARD
 
         # @return [Fixnum] the starting line number of the node
         def line
-          line_range && line_range.first
+          line_range && (line_range.begin || line_range.end)
         end
 
         # @return [String] the first line of source represented by the node.
@@ -345,8 +345,8 @@ module YARD
           elsif !children.empty?
             f = children.first
             l = children.last
-            self.line_range = Range.new(f.line_range.first, l.line_range.last)
-            self.source_range = Range.new(f.source_range.first, l.source_range.last)
+            self.line_range = Range.new(f.line_range.begin, l.line_range.end)
+            self.source_range = Range.new(f.source_range.begin, l.source_range.end)
           elsif @fallback_line || @fallback_source
             self.line_range = @fallback_line
             self.source_range = @fallback_source
@@ -431,7 +431,8 @@ module YARD
           # shape is (required, optional, rest, more, keyword, keyword_rest, block)
           # Ruby 3.1 moves :args_forward from rest to keyword_rest
           args_index = YARD.ruby31? ? -2 : 2
-          self[args_index].type == :args_forward if self[args_index]
+          node = self[args_index]
+          node.is_a?(AstNode) && node.type == :args_forward
         end
       end
 

data/lib/yard/parser/ruby/legacy/ruby_lex.rb

@@ -656,7 +656,7 @@ module YARD
           if @lex_state != EXPR_END && @lex_state != EXPR_CLASS &&
              (@lex_state != EXPR_ARG || @space_seen)
             c = peek(0)
-            tk = identify_here_document if /[-\w\"\'\`]/ =~ c
+            tk = identify_here_document if /[-~\w\"\'\`]/ =~ c
           end
           if !tk
             @lex_state = EXPR_BEG
@@ -978,7 +978,7 @@ module YARD
       end
 
       def identify_identifier
-        token = ""
+        token = String.new
         token.concat getc if peek(0) =~ /[$@]/
         token.concat getc if peek(0) == "@"
 
@@ -1063,6 +1063,8 @@ module YARD
         ch = getc
         if ch == "-"
           ch = getc
+        elsif ch == "~"
+          ch = getc
           indent = true
         end
         if /['"`]/ =~ ch # '
@@ -1096,9 +1098,12 @@ module YARD
         str = String.new
         while (l = gets)
           l.chomp!
-          l.strip! if indent
-          break if l == quoted
-          str << l.chomp << "\n"
+          if l == quoted
+            str = dedent(str) if indent
+            break
+          else
+            str << l.chomp << "\n"
+          end
         end
 
         @reader.divert_read_from(reserve)
@@ -1108,6 +1113,16 @@ module YARD
         Token(Ltype2Token[lt], str).set_text(str.dump)
       end
 
+      def dedent(str)
+        lines = str.split("\n", -1)
+        dedent_amt = lines.map do |line|
+          line =~ /\S/ ? line.match(/^ */).offset(0)[1] : nil
+        end.compact.min || 0
+        return str if dedent_amt.zero?
+
+        lines.map { |line| line =~ /\S/ ? line.gsub(/^ {#{dedent_amt}}/, "") : line }.join("\n")
+      end
+
       def identify_quotation(initial_char)
         ch = getc
         if lt = PERCENT_LTYPE[ch]

data/lib/yard/parser/ruby/ruby_parser.rb

@@ -236,14 +236,25 @@ module YARD
 
         def visit_event(node)
           map = @map[MAPPINGS[node.type]]
-          lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
+
+          # Pattern matching and `in` syntax creates :case nodes without 'case' tokens,
+          # fall back to the first child node.
+          if node.type == :case && (!map || map.empty?) && (child_node = node[0])
+            lstart = child_node.line_range.first
+            sstart = child_node.source_range.first
+          else
+            lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
+          end
+
+          raise "Cannot determine start of node #{node} around #{file}:#{lineno}" if lstart.nil? || sstart.nil?
+
           node.source_range = Range.new(sstart, @ns_charno - 1)
           node.line_range = Range.new(lstart, lineno)
           if node.respond_to?(:block)
             sr = node.block.source_range
             lr = node.block.line_range
-            node.block.source_range = Range.new(sr.first, @tokens.last[2][1] - 1)
-            node.block.line_range = Range.new(lr.first, @tokens.last[2][0])
+            node.block.source_range = Range.new(sr.begin, @tokens.last[2][1] - 1)
+            node.block.line_range = Range.new(lr.begin, @tokens.last[2][0])
           end
           node
         end
@@ -259,7 +270,10 @@ module YARD
         def visit_ns_token(token, data, ast_token = false)
           add_token(token, data)
           ch = charno
-          @last_ns_token = [token, data]
+
+          # For purposes of tracking parsing state, don't treat keywords as such
+          # where used as a symbol identifier.
+          @last_ns_token = [@last_ns_token && @last_ns_token.first == :symbeg ? :symbol : token, data]
           @charno += data.length
           @ns_charno = charno
           @newline = [:semicolon, :comment, :kw, :op, :lparen, :lbrace].include?(token)
@@ -272,14 +286,14 @@ module YARD
           if @percent_ary
             if token == :words_sep && data !~ /\s\z/
               rng = @percent_ary.source_range
-              rng = Range.new(rng.first, rng.last + data.length)
+              rng = Range.new(rng.begin, rng.end.to_i + data.length)
               @percent_ary.source_range = rng
               @tokens << [token, data, [lineno, charno]]
               @percent_ary = nil
               return
             elsif token == :tstring_end && data =~ /\A\s/
               rng = @percent_ary.source_range
-              rng = Range.new(rng.first, rng.last + data.length)
+              rng = Range.new(rng.begin, rng.end.to_i + data.length)
               @percent_ary.source_range = rng
               @tokens << [token, data, [lineno, charno]]
               @percent_ary = nil
@@ -377,8 +391,8 @@ module YARD
         def on_aref(*args)
           @map[:lbracket].pop
           ll, lc = *@map[:aref].shift
-          sr = args.first.source_range.first..lc
-          lr = args.first.line_range.first..ll
+          sr = args.first.source_range.begin..lc
+          lr = args.first.line_range.begin..ll
           AstNode.new(:aref, args, :char => sr, :line => lr)
         end
 
@@ -390,7 +404,7 @@ module YARD
 
         def on_array(other)
           node = AstNode.node_class_for(:array).new(:array, [other])
-          map = @map[MAPPINGS[node.type]]
+          map = @map[MAPPINGS[node.type]] if other.nil? || other.type == :list
           if map && !map.empty?
             lstart, sstart = *map.pop
             node.source_range = Range.new(sstart, @ns_charno - 1)
@@ -449,8 +463,8 @@ module YARD
             def on_#{kw}(*args)
               mapping = @map[#{kw.to_s.sub(/_mod$/, '').inspect}]
               mapping.pop if mapping
-              sr = args.last.source_range.first..args.first.source_range.last
-              lr = args.last.line_range.first..args.first.line_range.last
+              sr = args.last.source_range.begin..args.first.source_range.end
+              lr = args.last.line_range.begin..args.first.line_range.end
               #{node_class}.new(:#{kw}, args, :line => lr, :char => sr)
             end
           eof
@@ -473,8 +487,8 @@ module YARD
             begin; undef on_#{kw}_add; rescue NameError; end
             def on_#{kw}_add(list, item)
               last = @source[@ns_charno,1] == "\n" ? @ns_charno - 1 : @ns_charno
-              list.source_range = (list.source_range.first..last)
-              list.line_range = (list.line_range.first..lineno)
+              list.source_range = (list.source_range.begin..last)
+              list.line_range = (list.line_range.begin..lineno)
               list.push(item)
               list
             end
@@ -485,9 +499,9 @@ module YARD
           node = visit_event_arr(LiteralNode.new(:string_literal, args))
           if args.size == 1
             r = args[0].source_range
-            if node.source_range != Range.new(r.first - 1, r.last + 1)
+            if node.source_range != Range.new(r.begin - 1, r.end + 1)
               klass = AstNode.node_class_for(node[0].type)
-              r = Range.new(node.source_range.first + 1, node.source_range.last - 1)
+              r = Range.new(node.source_range.begin + 1, node.source_range.end - 1)
               node[0] = klass.new(node[0].type, [@source[r]], :line => node.line_range, :char => r)
             end
           end
@@ -573,7 +587,7 @@ module YARD
             @comments_flags[lineno] = @comments_flags[lineno - 1]
             @comments_flags.delete(lineno - 1)
             range = @comments_range.delete(lineno - 1)
-            source_range = range.first..source_range.last
+            source_range = range.begin..source_range.end
             comment = append_comment + "\n" + comment
           end
 
@@ -627,11 +641,13 @@ module YARD
             end
 
             # check upwards from line before node; check node's line at the end
-            ((node.line - 1).downto(node.line - 2).to_a + [node.line]).each do |line|
-              comment = @comments[line]
-              if comment && !comment.empty?
-                add_comment(line, node)
-                break
+            if (n_l = node.line)
+              ((n_l - 1).downto(n_l - 2).to_a + [n_l]).each do |line|
+                comment = @comments[line]
+                if comment && !comment.empty?
+                  add_comment(line, node)
+                  break
+                end
               end
             end
 
@@ -656,6 +672,23 @@ module YARD
             end
           end unless @comments.empty?
 
+          # Attach comments that fall within an otherwise empty
+          # class or module body. Without this step, a comment used
+          # solely for directives (like @!method) would be treated as
+          # a top-level comment and its directives would not be scoped
+          # to the namespace.
+          unless @comments.empty?
+            root.traverse do |node|
+              next unless [:class, :module, :sclass].include?(node.type)
+              body = node.children.last
+              next unless body && body.type == :list && body.empty?
+              @comments.keys.each do |line|
+                next unless node.line_range.include?(line)
+                add_comment(line, nil, body, true)
+              end
+            end
+          end
+
           # insert all remaining comments
           @comments.each do |line, _comment|
             add_comment(line, nil, root, true)

data/lib/yard/parser/source_parser.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 require 'stringio'
-require 'ostruct'
 
 module YARD
   module Parser
@@ -108,7 +107,8 @@ module YARD
           files = [paths].flatten.
             map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c,cc,cxx,cpp}" : p }.
             map {|p| p.include?("*") ? Dir[p].sort_by {|d| [d.length, d] } : p }.flatten.
-            reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }
+            reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }.
+            map {|p| p.encoding == Encoding.default_external ? p : p.dup.force_encoding(Encoding.default_external) }
 
           log.enter_level(level) do
             parse_in_order(*files.uniq)

data/lib/yard/tags/default_factory.rb

@@ -143,6 +143,7 @@ module YARD
         seen_space = false
         i = 0
         last_seen = ''
+        text ||= ''
         while i < text.length
           c = text[i, 1]
 

data/lib/yard/tags/directives.rb

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

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

data/lib/yard/tags/types_explainer.rb

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

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/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

data/lib/yard/templates/helpers/markup/rdoc_markup.rb

@@ -38,6 +38,7 @@ module YARD
           @@formatter = nil
           @@markup = nil
 
+          # @param text [String]
           def initialize(text)
             @text = text
 
@@ -47,6 +48,7 @@ module YARD
             end
           end
 
+          # @return [String]
           def to_html
             html = nil
             @@mutex.synchronize do

data/lib/yard/templates/template_options.rb

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

data/lib/yard/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module YARD
-  VERSION = '0.9.36'
+  VERSION = '0.9.38'
 end

data/templates/default/fulldoc/html/css/full_list.css

@@ -20,8 +20,8 @@ h1 { padding: 12px 10px; padding-bottom: 0; margin: 0; font-size: 1.4em; }
 #content.insearch #noresults { margin-left: 7px; }
 li.collapsed ul { display: none; }
 li a.toggle { cursor: default; position: relative; left: -5px; top: 4px; text-indent: -999px; width: 10px; height: 9px; margin-left: -10px; display: block; float: left; background: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAYAAABb0P4QAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAK8AAACvABQqw0mAAAABx0RVh0U29mdHdhcmUAQWRvYmUgRmlyZXdvcmtzIENTM5jWRgMAAAAVdEVYdENyZWF0aW9uIFRpbWUAMy8xNC8wOeNZPpQAAAE2SURBVDiNrZTBccIwEEXfelIAHUA6CZ24BGaWO+FuzZAK4k6gg5QAdGAq+Bxs2Yqx7BzyL7Llp/VfzZeQhCTc/ezuGzKKnKSzpCxXJM8fwNXda3df5RZETlIt6YUzSQDs93sl8w3wBZxCCE10GM1OcWbWjB2mWgEH4Mfdyxm3PSepBHibgQE2wLe7r4HjEidpnXMYdQPKEMJcsZ4zs2POYQOcaPfwMVOo58zsAdMt18BuoVDPxUJRacELbXv3hUIX2vYmOUvi8C8ydz/ThjXrqKqqLbDIAdsCKBd+Wo7GWa7o9qzOQHVVVXeAbs+yHHCH4aTsaCOQqunmUy1yBUAXkdMIfMlgF5EXLo2OpV/c/Up7jG4hhHcYLgWzAZXUc2b2ixsfvc/RmNNfOXD3Q/oeL9axJE1yT9IOoUu6MGUkAAAAAElFTkSuQmCC) no-repeat bottom left; }
-li.collapsed a.toggle { opacity: 0.5; cursor: default; background-position: top left; }
-li { color: #888; cursor: pointer; }
+li.collapsed a.toggle { cursor: default; background-position: top left; }
+li { color: #666; cursor: pointer; }
 li.deprecated { text-decoration: line-through; font-style: italic; }
 li.odd { background: #f0f0f0; }
 li.even { background: #fafafa; }
@@ -47,7 +47,7 @@ li small { display: block; font-size: 0.8em; }
 li small:before { content: ""; }
 li small:after { content: ""; }
 li small.search_info { display: none; }
-#search { width: 170px; position: static; margin: 3px; margin-left: 10px; font-size: 0.9em; color: #888; padding-left: 0; padding-right: 24px; }
+#search { width: 170px; position: static; margin: 3px; margin-left: 10px; font-size: 0.9em; color: #666; padding-left: 0; padding-right: 24px; }
 #content.insearch #search { background-position: center right; }
 #search input { width: 110px; }
 

data/templates/default/fulldoc/html/css/style.css

@@ -9,8 +9,6 @@ body {
   margin: 0;
   padding: 0;
   display: flex;
-  display: -webkit-flex;
-  display: -ms-flexbox;
 }
 
 #nav {
@@ -28,11 +26,7 @@ body {
   height: 100%;
   position: relative;
   display: flex;
-  display: -webkit-flex;
-  display: -ms-flexbox;
   flex-shrink: 0;
-  -webkit-flex-shrink: 0;
-  -ms-flex: 1 0;
 }
 #resizer {
   position: absolute;
@@ -45,8 +39,6 @@ body {
 }
 #main {
   flex: 5 1;
-  -webkit-flex: 5 1;
-  -ms-flex: 5 1;
   outline: none;
   position: relative;
   background: #fff;
@@ -56,7 +48,8 @@ body {
 }
 
 @media (max-width: 920px) {
-  .nav_wrap { width: 100%; top: 0; right: 0; overflow: visible; position: absolute; }
+  body { display: block; }
+  .nav_wrap { width: 80vw !important; top: 0; right: 0; overflow: visible; position: absolute; }
   #resizer { display: none; }
   #nav {
     z-index: 9999;
@@ -82,6 +75,11 @@ body {
   #search { display: none; }
 }
 
+@media (max-width: 320px) {
+  body { height: 100%; overflow: hidden; overflow-wrap: break-word; }
+  #main { height: 100%; overflow: auto; }
+}
+
 #main img { max-width: 100%; }
 h1 { font-size: 25px; margin: 1em 0 0.5em; padding-top: 4px; border-top: 1px dotted #d5d5d5; }
 h1.noborder { border-top: 0px; margin-top: 0; padding-top: 4px; }
@@ -106,6 +104,7 @@ h2 small a {
   position: relative;
   padding: 2px 7px;
 }
+a { font-weight: 550; }
 .clear { clear: both; }
 .inline { display: inline; }
 .inline p:first-child { display: inline; }
@@ -199,13 +198,9 @@ p.inherited {
   width: 100%;
   font-size: 1em;
   display: flex;
-  display: -webkit-flex;
-  display: -ms-flexbox;
 }
 .box_info dl dt {
   flex-shrink: 0;
-  -webkit-flex-shrink: 1;
-  -ms-flex-shrink: 1;
   width: 100px;
   text-align: right;
   font-weight: bold;
@@ -216,8 +211,6 @@ p.inherited {
 }
 .box_info dl dd {
   flex-grow: 1;
-  -webkit-flex-grow: 1;
-  -ms-flex: 1;
   max-width: 420px;
   padding: 6px 0;
   padding-right: 20px;

data/templates/default/fulldoc/html/full_list.erb

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html>
+<html <%= "lang=\"#{html_lang}\"" unless html_lang.nil? %>>
   <head>
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta charset="<%= charset %>" />
@@ -26,7 +26,10 @@
           <% end %>
         </div>
 
-        <div id="search">Search: <input type="text" /></div>
+        <div id="search">
+          <label for="search-class">Search:</label>
+          <input id="search-class" type="text" />
+        </div>
       </div>
 
       <ul id="full_list" class="<%= @list_class || @list_type %>">