yard 0.9.36 → 0.9.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1f492861606b6ce24d390317f2a97ccbd67bbf73b8b964ea6f9e61bb4096d9e
-  data.tar.gz: 1a4ec96bd604c8ab68cf6c971fc22aff400f2d8ed853d3b0b5fc222f4c8e7767
+  metadata.gz: 0774d1772b133075737690acbc502767f6fef28d3765a14929074259248f3981
+  data.tar.gz: '068103b3caf24a6c6071a6c9b0f52bd58641fd0c03e22220fb2d1b09a104385c'
 SHA512:
-  metadata.gz: 04b727cb198fd9559a9314989fae7bcf60202531f5ab634d211780b5bbf15b60341d8a8f5fa6fd890c743c7d1b953e7b49d3c8e73997f3397b7344a70442fd29
-  data.tar.gz: c3df5e59c450adfc6d6088bd7c6a6c64f4477c1de65eae7cbd21e1c4ca410d606179bc88c84ed084b22d7b3f8bf66cc67426e9c103558b0a25c5ab01c1900ab9
+  metadata.gz: 64a799b2f45d7ad6aad8684c805344f242c8e2f8ef1c60a43094bc237bccd449ee1c93c60c0f54a36f05a79e5b652636d7170dce85941b1f74a4bcc173c92c21
+  data.tar.gz: b19ba690f1a244b0c7df5c1524f77355323fa9164e9496c609f258b3d0691c0a3d807cd985f20f335884ba1d8e97193149d4a7b9e1eebd9ed3a43431492a1ce3

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # main
 
+# [0.9.37] - September 4th, 2024
+
+[0.9.37]: https://github.com/lsegal/yard/compare/v0.9.36...v0.9.37
+
+- Fix JavaScript errors in `--one-file` template (#1426)
+- Fix heredoc parsing and add support for squiggly heredocs (#1315, #1495)
+- Accessibility improvements to the default template (#1501)
+- Improved YARD documentation (#1410, #1512, #1516, #1544)
+- Fix error when parsing `@option` tags (#1515)
+- Fix issue parsing UTF-8 filenames (#1517)
+- Replace OpenStruct with optimized YARD::OpenStruct to avoid ostruct performance warnings (#1545)
+- Add support for `private attr_*` syntax (#1541)
+- Remove logger dependency (#1546)
+
 # [0.9.36] - February 29th, 2024
 
 [0.9.36]: https://github.com/lsegal/yard/compare/v0.9.35...v0.9.36

data/README.md

@@ -122,6 +122,13 @@ HTML. If running `which rdoc` turns up empty, install RDoc by issuing:
 $ sudo apt-get install rdoc
 ```
 
+### Markdown parser
+
+When rendering markdown, yard will use one of several possible markdown providers,
+[in order of priority](https://github.com/lsegal/yard/blob/e833aac7a01510245dd4ae1d1d18b046c8293c2d/lib/yard/templates/helpers/markup_helper.rb#L26-L33).
+If you are experiencing rendering bugs (example [1](https://github.com/lsegal/yard/issues/1410) [2](https://github.com/lsegal/yard/issues/1543)), try adding one of the
+gems further up in the list to your Gemfile.
+
 ## Usage
 
 There are a couple of ways to use YARD. The first is via command-line, and the
@@ -185,7 +192,7 @@ Note that the README file can be specified with its own `--readme` switch.
 You can also add a `.yardopts` file to your project directory which lists the
 switches separated by whitespace (newlines or space) to pass to yardoc whenever
 it is run. A full overview of the `.yardopts` file can be found in
-{YARD::CLI::Yardoc}.
+[YARD::CLI::Yardoc](https://rubydoc.info/gems/yard/YARD/CLI/Yardoc#label-Options+File+-28.yardopts-29).
 
 ### Queries
 

data/lib/yard/autoload.rb

@@ -298,6 +298,7 @@ module YARD
   autoload :DocstringParser,  __p('docstring_parser')
   autoload :GemIndex,         __p('gem_index')
   autoload :Logger,           __p('logging')
+  autoload :OpenStruct,       __p('open_struct')
   autoload :Options,          __p('options')
   autoload :Registry,         __p('registry')
   autoload :RegistryResolver, __p('registry_resolver')

data/lib/yard/code_objects/macro_object.rb

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

data/lib/yard/docstring_parser.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-require 'ostruct'
 
 module YARD
   # Parses text and creates a {Docstring} object to represent documentation

data/lib/yard/handlers/processor.rb

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

data/lib/yard/handlers/ruby/visibility_handler.rb

@@ -13,10 +13,22 @@ class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
     case statement.type
     when :var_ref, :vcall
       self.visibility = ident.first.to_sym
-    when :fcall, :command
+    when :command
+      if RUBY_VERSION >= '3.' && is_attribute_method?(statement.parameters.first)
+        parse_block(statement.parameters.first, visibility: ident.first.to_sym)
+        return
+      end
+      process_decorator do |method|
+        method.visibility = ident.first if method.respond_to? :visibility=
+      end
+    when :fcall
       process_decorator do |method|
         method.visibility = ident.first if method.respond_to? :visibility=
       end
     end
   end
+
+  def is_attribute_method?(node)
+    node.type == :command && node.jump(:ident).first.to_s =~ /^attr_(accessor|writer|reader)$/
+  end
 end

data/lib/yard/logging.rb

@@ -1,12 +1,44 @@
 # encoding: utf-8
 # frozen_string_literal: true
-require 'logger'
 require 'thread'
 
 module YARD
   # Handles console logging for info, warnings and errors.
   # Uses the stdlib Logger class in Ruby for all the backend logic.
-  class Logger < ::Logger
+  class Logger
+    # Log severity levels
+    module Severity
+      # Debugging log level
+      DEBUG = 0
+
+      # Information log level
+      INFO = 1
+
+      # Warning log level
+      WARN = 2
+
+      # Error log level
+      ERROR = 3
+
+      # Fatal log level
+      FATAL = 4
+
+      # Unknown log level
+      UNKNOWN = 5
+
+      # @private
+      SEVERITIES = {
+        DEBUG => :debug,
+        INFO => :info,
+        WARN => :warn,
+        ERROR => :error,
+        FATAL => :fatal,
+        UNKNOWN => :unknown
+      }
+    end
+
+    include Severity
+
     # The list of characters displayed beside the progress bar to indicate
     # "movement".
     # @since 0.8.2
@@ -14,25 +46,31 @@ module YARD
 
     # @return [IO] the IO object being logged to
     # @since 0.8.2
-    def io; @logdev end
-    def io=(pipe) @logdev = pipe end
+    attr_accessor :io
 
     # @return [Boolean] whether backtraces should be shown (by default
     #   this is on).
     def show_backtraces; @show_backtraces || level == DEBUG end
     attr_writer :show_backtraces
 
+    # @return [DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN] the logging level
+    attr_accessor :level
+
+    # @return [Boolean] whether a warn message has been emitted. Used for status tracking.
+    attr_accessor :warned
+
     # @return [Boolean] whether progress indicators should be shown when
     #   logging CLIs (by default this is off).
     def show_progress
       return false if YARD.ruby18? # threading is too ineffective for progress support
-      return false if YARD.windows? # windows has poor ANSI support
       return false unless io.tty? # no TTY support on IO
       return false unless level > INFO # no progress in verbose/debug modes
       @show_progress
     end
     attr_writer :show_progress
 
+    # @!group Constructor Methods
+
     # The logger instance
     # @return [Logger] the logger instance
     def self.instance(pipe = STDOUT)
@@ -40,13 +78,12 @@ module YARD
     end
 
     # Creates a new logger
+    # @private
     def initialize(pipe, *args)
-      super(pipe, *args)
       self.io = pipe
       self.show_backtraces = true
       self.show_progress = false
       self.level = WARN
-      self.formatter = method(:format_log)
       self.warned = false
       @progress_indicator = 0
       @mutex = Mutex.new
@@ -54,36 +91,64 @@ module YARD
       @progress_last_update = Time.now
     end
 
-    # Changes the debug level to DEBUG if $DEBUG is set
-    # and writes a debugging message.
-    def debug(*args)
-      self.level = DEBUG if $DEBUG
-      super
+    # @!macro [attach] logger.create_log_method
+    #   @method $1(message)
+    #   Logs a message with the $1 severity level.
+    #   @param message [String] the message to log
+    #   @see #log
+    #   @return [void]
+    # @private
+    def self.create_log_method(name)
+      severity = Severity.const_get(name.to_s.upcase)
+      define_method(name) { |message| log(severity, message) }
     end
 
+    # @!group Logging Methods
+
+    create_log_method :info
+    create_log_method :error
+    create_log_method :fatal
+    create_log_method :unknown
+
+    # Changes the debug level to DEBUG if $DEBUG is set and writes a debugging message.
+    create_log_method :debug
+
     # Remembers when a warning occurs and writes a warning message.
-    def warn(*args)
-      self.warned = true
-      super
+    create_log_method :warn
+
+    # Logs a message with a given severity
+    # @param severity [DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN] the severity level
+    # @param message [String] the message to log
+    def log(severity, message)
+      self.level = DEBUG if $DEBUG
+      return unless severity >= level
+
+      self.warned = true if severity == WARN
+      clear_line
+      puts "[#{SEVERITIES[severity].to_s.downcase}]: #{message}"
     end
-    attr_accessor :warned
 
-    # Captures the duration of a block of code for benchmark analysis. Also
-    # calls {#progress} on the message to display it to the user.
+    # @!group Level Control Methods
+
+    # Sets the logger level for the duration of the block
     #
-    # @todo Implement capture storage for reporting of benchmarks
-    # @param [String] msg the message to display
-    # @param [Symbol, nil] nontty_log the level to log as if the output
-    #   stream is not a TTY. Use +nil+ for no alternate logging.
-    # @yield a block of arbitrary code to benchmark
-    # @return [void]
-    def capture(msg, nontty_log = :debug)
-      progress(msg, nontty_log)
+    # @example
+    #   log.enter_level(Logger::ERROR) do
+    #     YARD.parse_string "def x; end"
+    #   end
+    # @param [Fixnum] new_level the logger level for the duration of the block.
+    #   values can be found in Ruby's Logger class.
+    # @yield the block with the logger temporarily set to +new_level+
+    def enter_level(new_level = level)
+      old_level = level
+      self.level = new_level
       yield
     ensure
-      clear_progress
+      self.level = old_level
     end
 
+    # @!group Utility Printing Methods
+
     # Displays a progress indicator for a given message. This progress report
     # is only displayed on TTY displays, otherwise the message is passed to
     # the +nontty_log+ level.
@@ -120,7 +185,7 @@ module YARD
     # @since 0.8.2
     def clear_progress
       return unless show_progress
-      print_no_newline("\e[?25h\e[2K")
+      io.write("\e[?25h\e[2K")
       @progress_msg = nil
     end
 
@@ -133,16 +198,13 @@ module YARD
       print("#{msg}\n")
     end
 
-    alias print_no_newline <<
-    private :print_no_newline
-
     # Displays an unformatted line to the logger output stream.
     # @param [String] msg the message to display
     # @return [void]
     # @since 0.8.2
     def print(msg = '')
       clear_line
-      print_no_newline(msg)
+      io.write(msg)
     end
     alias << print
 
@@ -158,48 +220,41 @@ module YARD
         exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n")
     end
 
+    # @!group Benchmarking Methods
+
+    # Captures the duration of a block of code for benchmark analysis. Also
+    # calls {#progress} on the message to display it to the user.
+    #
+    # @todo Implement capture storage for reporting of benchmarks
+    # @param [String] msg the message to display
+    # @param [Symbol, nil] nontty_log the level to log as if the output
+    #   stream is not a TTY. Use +nil+ for no alternate logging.
+    # @yield a block of arbitrary code to benchmark
+    # @return [void]
+    def capture(msg, nontty_log = :debug)
+      progress(msg, nontty_log)
+      yield
+    ensure
+      clear_progress
+    end
+
+    # @!endgroup
+
     # Warns that the Ruby environment does not support continuations. Applies
     # to JRuby, Rubinius and MacRuby. This warning will only display once
     # per Ruby process.
     #
     # @deprecated Continuations are no longer needed by YARD 0.8.0+.
     # @return [void]
+    # @private
     def warn_no_continuations
     end
 
-    # Sets the logger level for the duration of the block
-    #
-    # @example
-    #   log.enter_level(Logger::ERROR) do
-    #     YARD.parse_string "def x; end"
-    #   end
-    # @param [Fixnum] new_level the logger level for the duration of the block.
-    #   values can be found in Ruby's Logger class.
-    # @yield the block with the logger temporarily set to +new_level+
-    def enter_level(new_level = level)
-      old_level = level
-      self.level = new_level
-      yield
-    ensure
-      self.level = old_level
-    end
-
     private
 
-    # Override this internal Logger method to clear line
-    def add(*args)
-      clear_line
-      super(*args)
-    end
-
     def clear_line
       return unless @progress_msg
-      print_no_newline("\e[2K\r")
-    end
-
-    # Log format (from Logger implementation). Used by Logger internally
-    def format_log(sev, _time, _prog, msg)
-      "[#{sev.downcase}]: #{msg}\n"
+      io.write("\e[2K\r")
     end
   end
 end

data/lib/yard/open_struct.rb

@@ -0,0 +1,67 @@
+module YARD
+  # An OpenStruct compatible struct class that allows for basic access of attributes
+  # via +struct.attr_name+ and +struct.attr_name = value+.
+  class OpenStruct
+    def initialize(hash = {})
+      @table = hash.each_pair { |k, v| [k.to_sym, v] }
+    end
+
+    # @private
+    def method_missing(name, *args)
+      if name.to_s.end_with?('=')
+        varname = name.to_s[0..-2].to_sym
+        __cache_lookup__(varname)
+        send(name, args.first)
+      else
+        __cache_lookup__(name)
+        send(name)
+      end
+    end
+
+    def to_h
+      @table.dup
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && to_h == other.to_h
+    end
+
+    def hash
+      @table.hash
+    end
+
+    def dig(*keys)
+      @table.dig(*keys)
+    end
+
+    def []=(key, value)
+      @table[key.to_sym] = value
+    end
+
+    def [](key)
+      @table[key.to_sym]
+    end
+
+    def each_pair(&block)
+      @table.each_pair(&block)
+    end
+
+    def marshal_dump
+      @table
+    end
+
+    def marshal_load(data)
+      @table = data
+    end
+
+    private
+
+    def __cache_lookup__(name)
+      key = name.to_sym.inspect
+      instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{name}; @table[#{key}]; end
+        def #{name.to_s.sub('?','_')}=(v); @table[#{key}] = v; end unless #{key}.to_s.include?('?')
+      RUBY
+    end
+  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
@@ -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/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/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

data/lib/yard/templates/engine.rb

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

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.37'
 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

@@ -82,6 +82,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 +111,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; }

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 %>">