yard 0.9.36 → 0.9.38

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1f492861606b6ce24d390317f2a97ccbd67bbf73b8b964ea6f9e61bb4096d9e
-  data.tar.gz: 1a4ec96bd604c8ab68cf6c971fc22aff400f2d8ed853d3b0b5fc222f4c8e7767
+  metadata.gz: a3a536051e6077e89b4ef2bc4ac2f30e60b8e65d33cdca957fed25644bf901a7
+  data.tar.gz: 6f4a7736baaeec0a55e7595b12f5828927fc46115e20e4dd919e96543541cbbd
 SHA512:
-  metadata.gz: 04b727cb198fd9559a9314989fae7bcf60202531f5ab634d211780b5bbf15b60341d8a8f5fa6fd890c743c7d1b953e7b49d3c8e73997f3397b7344a70442fd29
-  data.tar.gz: c3df5e59c450adfc6d6088bd7c6a6c64f4477c1de65eae7cbd21e1c4ca410d606179bc88c84ed084b22d7b3f8bf66cc67426e9c103558b0a25c5ab01c1900ab9
+  metadata.gz: b9a5348496a1778b2f4a7793df24716329a665fdabbe237932cd126c8309be4543d35b35a279e4ddb3cb31978c1b6e88ae0b799004ee79f2316d6896b9057201
+  data.tar.gz: f5c993f3808b9f5baca0c8fc1f92abeb7a113b1be7164dfd71b0b4bff98c58416ea5a82baf473780995d132bbbd7ffbbbffceddb01fda40993fac04bdb790cf8

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # main
 
+# [0.9.38] - December 5th, 2025
+
+[0.9.38]: https://github.com/lsegal/yard/compare/v0.9.37...v0.9.38
+
+- Add support for complex constant assignment (#1599)
+- Add support for Data type structs (#1600)
+- Support multi method duck type syntax in type explainer (#1631)
+- Improve Ruby 3.5 compatibility (#1616)
+- Update documentation for various type annotations (#1615)
+- JavaScript frontend updates (resizer, JS bugs, reduce console verbosity) for default template
+- Fix beginless/endless range errors (#1549, #1625)
+- Fix path structure in Templates.md documentation (#1588)
+- Fix signature handling in overload (#1590)
+- Fix handling of **nil with named block (#1623)
+- Fix directives in empty class bodies (#1624)
+- Fix parsing of array within array syntax (#1604)
+- Fix parsing of visibility keywords in front of class methods (#1632)
+
+# [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,12 +122,19 @@ 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
 second is the Rake task.
 
-**1. yard Command-line Tool**
+### 1. yard Command-line Tool
 
 YARD comes packaged with a executable named `yard` which can control the many
 functions of YARD, including generating documentation, graphs running the YARD
@@ -140,7 +147,7 @@ $ yard --help
 Plugins can also add commands to the `yard` executable to provide extra
 functionality.
 
-### Generating Documentation
+#### Generating Documentation
 
 <span class="note">The `yardoc` executable is a shortcut for `yard doc`.</span>
 
@@ -185,9 +192,9 @@ 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
+#### Queries
 
 The `yardoc` tool also supports a `--query` argument to only include objects
 that match a certain data or meta-data query. The query syntax is Ruby, though a
@@ -214,7 +221,7 @@ following two lines both check for the existence of a return and param tag:
 
 For more information about the query syntax, see the {YARD::Verifier} class.
 
-**2. Rake Task**
+### 2. Rake Task
 
 The second most obvious is to generate docs via a Rake task. You can do this by
 adding the following to your `Rakefile`:
@@ -240,7 +247,7 @@ environment variable:
 $ rake yard OPTS='--any --extra --opts'
 ```
 
-**3. `yri` RI Implementation**
+### 3. `yri` RI Implementation
 
 The yri binary will use the cached .yardoc database to give you quick ri-style
 access to your documentation. It's way faster than ri but currently does not
@@ -264,7 +271,7 @@ $ yard gems
 If you don't have sudo access, it will write these files to your `~/.yard`
 directory. `yri` will also cache lookups there.
 
-**4. `yard server` Documentation Server**
+### 4. `yard server` Documentation Server
 
 The `yard server` command serves documentation for a local project or all
 installed RubyGems. To serve documentation for a project you are working on,
@@ -278,14 +285,14 @@ And the project inside the current directory will be parsed (if the source has
 not yet been scanned by YARD) and served at
 [http://localhost:8808](http://localhost:8808).
 
-### Live Reloading
+#### Live Reloading
 
 If you want to serve documentation on a project while you document it so that
 you can preview the results, simply pass `--reload` (`-r`) to the above command
 and YARD will reload any changed files on each request. This will allow you to
 change any documentation in the source and refresh to see the new contents.
 
-### Serving Gems
+#### Serving Gems
 
 To serve documentation for all installed gems, call:
 
@@ -297,7 +304,7 @@ This will also automatically build documentation for any gems that have not been
 previously scanned. Note that in this case there will be a slight delay between
 the first request of a newly parsed gem.
 
-**5. `yard graph` Graphviz Generator**
+### 5. `yard graph` Graphviz Generator
 
 You can use `yard graph` to generate dot graphs of your code. This, of course,
 requires [Graphviz](http://www.graphviz.org) and the `dot` binary. By default

data/docs/Templates.md

@@ -280,10 +280,11 @@ seen above by creating such a path in our '/path/to/mytemplates' custom template
 path:
 
     /path/to/mytemplates/:
-    |-- class
-    |   |-- html
-    |   |   |-- customsection.erb
-    |   |-- setup.rb
+    |--default
+    |   |-- class
+    |   |   |-- html
+    |   |   |   |-- customsection.erb
+    |   |   |-- setup.rb
 
 The `setup.rb` file would look like:
 

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/base.rb

@@ -228,7 +228,7 @@ module YARD
       # @example Create class Z inside namespace X::Y
       #   CodeObjects::Base.new(P("X::Y"), :Z) # or
       #   CodeObjects::Base.new(Registry.root, "X::Y")
-      # @param [NamespaceObject] namespace the namespace the object belongs in,
+      # @param [NamespaceObject, :root, nil] namespace the namespace the object belongs in,
       #   {Registry.root} or :root should be provided if it is associated with
       #   the top level namespace.
       # @param [Symbol, String] name the name (or complex path) of the object.

data/lib/yard/code_objects/extra_file_object.rb

@@ -127,6 +127,7 @@ module YARD::CodeObjects
     end
 
     def translate(data)
+      return data if locale.nil?
       text = YARD::I18n::Text.new(data, :have_header => true)
       text.translate(YARD::Registry.locale(locale))
     end

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/base.rb

@@ -462,6 +462,18 @@ module YARD
           end
         end
 
+        if docstring.is_a?(String)
+          if (m = docstring.match(/^\s*@!?visibility\s+(public|private|protected)\b/m))
+            vis_sym = m[1].to_sym
+
+            if object.nil?
+              globals.visibility_origin = :directive
+            elsif object.is_a?(CodeObjects::MethodObject)
+              object.visibility = vis_sym
+            end
+          end
+        end
+
         register_transitive_tags(object)
       end
 
@@ -511,7 +523,17 @@ module YARD
       def register_visibility(object, visibility = self.visibility)
         return unless object.respond_to?(:visibility=)
         return if object.is_a?(NamespaceObject)
-        object.visibility = visibility
+
+        if object.is_a?(CodeObjects::MethodObject)
+          origin = globals.visibility_origin
+          if origin == :keyword
+            object.visibility = visibility if object.scope == scope
+          else
+            object.visibility = visibility
+          end
+        else
+          object.visibility = visibility
+        end
       end
 
       # Registers the same method information on the module function, if

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/constant_handler.rb

@@ -9,6 +9,9 @@ class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
     if statement[1].call? && statement[1][0][0] == s(:const, "Struct") &&
        statement[1][2] == s(:ident, "new")
       process_structclass(statement)
+    elsif statement[1].call? && statement[1][0][0] == s(:const, "Data") &&
+       statement[1][2] == s(:ident, "define")
+      process_dataclass(statement)
     elsif statement[0].type == :var_field && statement[0][0].type == :const
       process_constant(statement)
     elsif statement[0].type == :const_path_field
@@ -31,20 +34,34 @@ class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
   end
 
   def process_structclass(statement)
-    lhs = statement[0][0]
-    if lhs.type == :const
-      klass = create_class(lhs[0], P(:Struct))
+    lhs = statement[0]
+    if (lhs.type == :var_field && lhs[0].type == :const) || lhs.type == :const_path_field
+      klass = create_class(lhs.source, P(:Struct))
       create_attributes(klass, extract_parameters(statement[1]))
       parse_block(statement[1].block[1], :namespace => klass) unless statement[1].block.nil?
     else
-      raise YARD::Parser::UndocumentableError, "Struct assignment to #{statement[0].source}"
+      raise YARD::Parser::UndocumentableError, "Struct assignment to #{lhs.source}"
     end
   end
 
-  # Extract the parameters from the Struct.new AST node, returning them as a list
+  def process_dataclass(statement)
+    lhs = statement[0]
+    if (lhs.type == :var_field && lhs[0].type == :const) || lhs.type == :const_path_field
+      klass = create_class(lhs.source, P(:Data))
+      extract_parameters(statement[1]).each do |member|
+        klass.attributes[:instance][member] = SymbolHash[:read => nil, :write => nil]
+        create_reader(klass, member)
+      end
+      parse_block(statement[1].block[1], :namespace => klass) unless statement[1].block.nil?
+    else
+      raise YARD::Parser::UndocumentableError, "Data assignment to #{lhs.source}"
+    end
+  end
+
+  # Extract the parameters from the Struct.new or Data.define AST node, returning them as a list
   # of strings
   #
-  # @param [MethodCallNode] superclass the AST node for the Struct.new call
+  # @param [MethodCallNode] superclass the AST node for the Struct.new or Data.define call
   # @return [Array<String>] the member names to generate methods for
   def extract_parameters(superclass)
     return [] unless superclass.parameters

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

@@ -8,9 +8,10 @@ class YARD::Handlers::Ruby::Legacy::VisibilityHandler < YARD::Handlers::Ruby::Le
     vis = statement.tokens.first.text
     if statement.tokens.size == 1
       self.visibility = vis
+      globals.visibility_origin = :keyword
     else
       tokval_list(statement.tokens[2..-1], :attr).each do |name|
-        MethodObject.new(namespace, name, scope) {|o| o.visibility = vis }
+        MethodObject.new(namespace, name, scope) { |o| o.visibility = vis }
       end
     end
   end

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

@@ -13,10 +13,23 @@ 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
+      globals.visibility_origin = :keyword
+    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