yard 0.9.28 → 0.9.43

data/docs/WhatsNew.md

@@ -1,5 +1,57 @@
 # @title What's New?
 
+# What's New in 0.9.x?
+
+## Support for Ruby Signature Files (.rbs) (0.9.40)
+
+YARD now supports parsing Ruby signature files (.rbs) with full docstring support. This means you can write your documentation in `.rbs` files and have it show up in generated documentation, and use `.rbs` files alongside `.rb` sources to supplement type and API information.
+
+## New built-in Markdown renderer (0.9.40)
+
+YARD now ships with a built-in Markdown renderer (`YARD::Templates::Helpers::Markup::HybridMarkdown`)
+that requires **no external gems**. It supports a practical subset of GitHub Flavored Markdown (GFM)
+as well as common RDoc markup forms, including:
+
+- Headings (`#`, `=`)
+- Fenced code blocks (`` ``` `` and `~~~`) as well as RDoc formatted `+text+` blocks.
+- Tables, blockquotes, and thematic breaks
+- Ordered and unordered lists (including RDoc-style)
+- Inline emphasis, code, links, and images
+- HTML passthrough blocks
+
+This renderer is the **default** for both the `rdoc` and `markdown` markup types—no gem
+installation required. If an optional provider gem (e.g. `redcarpet`, `kramdown`,
+`commonmarker`) is installed and selected, YARD will use it instead for extra features such
+as custom extensions or stricter spec compliance.
+
+## `#-` comment block separators (0.9.40)
+
+YARD now recognizes a trailing `#-` line as a separator between comment
+blocks. This is useful when you want to keep a file header comment at the top
+of a Ruby file without having that header attach itself to the first class,
+module or method in the file.
+
+For example:
+
+    # Copyright (c) Example Corp
+    # This file defines support code shared by the client.
+    #-
+
+    class Client
+    end
+
+In the example above, the file header stays disconnected from `Client`.
+Note that `# -` does **not** act as a separator; only an attached `#-`
+line has this behavior.
+
+## Ruby 4.x support (0.9.39)
+
+Added support for Ruby 4.x along with new syntaxes.
+
+## Other changes
+
+See the [CHANGELOG](CHANGELOG.md) for a full list of changes in 0.9.x.
+
 # What's New in 0.8.x?
 
 1. **Directives (new behavioural tag syntax)** (0.8.0)
@@ -92,7 +144,7 @@ methods are defined dynamically and not associated with any code.
 #### New `@!parse` directive to parse Ruby code
 
 A new {tag:!parse} directive was added that allows a developer to have
-YARD parse code that might not necessarily be parseable in its original
+YARD parse code that might not necessarily be parsable in its original
 form. This is useful when using `instance_eval` and other dynamic
 meta-programming techniques to define methods or perform functionality.
 For instance, a common case of the "self.included" callback in module
@@ -171,7 +223,7 @@ only mixins inside of a "Foo::Bar" namespace by doing:
 YARD now ships with the beginnings of internationalization support
 for translating documentation into multiple languages. The
 `yard i18n` command now allows you to generate ".pot" and ultimately
-".po" files for translation with [gettext](http://www.gnu.org/software/gettext).
+".po" files for translation with [gettext](https://www.gnu.org/software/gettext).
 
 Note that this tool is a small step in the larger transition for
 proper I18n support in YARD. We still have to add proper gettext
@@ -283,7 +335,7 @@ above example would be:
 But note that `--query` does not work when YARD is in "safe mode"
 due to security concerns, whereas `--api` works in either mode.
 This enables `--api` to function on remote documentation sites like
-[rubydoc.info](http://rubydoc.info).
+[rubydoc.info](https://rubydoc.info).
 
 ## Added `--non-transitive-tag` to disable transitive tag (0.8.3)
 
@@ -307,7 +359,7 @@ with `yard server -B PORT` or `yard server --bind PORT`.
 
 Support for the AsciiDoc markup type is now introduced using the `asciidoc`
 markup type (`yard doc -m asciidoc`). Requires the
-[asciidoctor](http://rubygems.org/gems/asciidoctor) RubyGem library to be
+[asciidoctor](https://rubygems.org/gems/asciidoctor) RubyGem library to be
 installed before running YARD.
 
 ## Added `yard markups` command to list available markup types (0.8.6)
@@ -645,7 +697,7 @@ templates. To serve documentation for installed gems:
   will do this for you on-the-fly. It is therefore possible to speed up your
   gem installs by using `gem install GEMNAME --no-rdoc` without repercussion.
   You can also add this switch to your `~/.gemrc` file so that you don't need
-   to re-type it each time. See [this link](http://stackoverflow.com/questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install)
+   to re-type it each time. See [this link](https://stackoverflow.com/questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install)
    for exact instructions.</span>
 
 ## Groups support for method listing (0.6.0)
@@ -718,7 +770,7 @@ regular diffing tells you which lines have been added/removed in a file,
 object diffing allows you to see what classes/methods/modules have been
 added/removed between versions of a codebase.
 
-For an overview of how to use `yard diff`, see [YARD Object Oriented Diffing](http://gnuu.org/2010/06/26/yard-object-oriented-diffing/).
+For an overview of how to use `yard diff`, see [YARD Object Oriented Diffing](https://gnuu.org/2010/06/26/yard-object-oriented-diffing/).
 
 ## `yard stats` to display statistics and undocumented objects (0.6.0)
 
@@ -902,7 +954,7 @@ Support for documenting native Ruby C code (0.5.0)
 
 It is now possible to document native Ruby extensions with YARD with a new
 C parser mostly borrowed from RDoc. This enables the ability to document
-Ruby's core and stdlibs which will be hosted on http://yardoc.org/docs. In
+Ruby's core and stdlibs which will be hosted on https://yardoc.org/docs. In
 addition, the .yardoc dump for the Ruby-core classes will become available
 as an installable gem for yri support (see #3).
 
@@ -1144,7 +1196,7 @@ Default rake task is now `rake yard`
 Not a big change, but anyone using the default "rake yardoc" task should
 update their scripts:
 
-[http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0](http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0)
+[https://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0](https://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0)
 
 
 What's New in 0.2.3.x?
@@ -1204,7 +1256,7 @@ that is actually being employed. Here's an example:
       # @overload def to_html(html, autolink = true)
       #   This docstring describes the specific overload only.
       #   @param [String] html the HTML
-      #   @param [Boolean] autolink whether or not to atuomatically link
+      #   @param [Boolean] autolink whether or not to automatically link
       #     URL references
       # @overload def to_html(html, opts = {})
       #   @param [String] html the HTML

data/docs/templates/default/yard_tags/html/setup.rb

@@ -22,5 +22,5 @@ def tag_signature(tag)
             else
               "description"
             end
-  signature + h(extra).gsub(/\n/, "<br/>&nbsp;&nbsp;&nbsp;")
+  signature + h(extra).gsub(/\n/, "<br>&nbsp;&nbsp;&nbsp;")
 end

data/lib/yard/autoload.rb

@@ -69,6 +69,16 @@ module YARD
       autoload :MethodHandler,            __p('handlers/common/method_handler')
     end
 
+    # RBS type signature handlers
+    module RBS
+      autoload :Base,               __p('handlers/rbs/base')
+      autoload :AttributeHandler,   __p('handlers/rbs/attribute_handler')
+      autoload :ConstantHandler,    __p('handlers/rbs/constant_handler')
+      autoload :MethodHandler,      __p('handlers/rbs/method_handler')
+      autoload :MixinHandler,       __p('handlers/rbs/mixin_handler')
+      autoload :NamespaceHandler,   __p('handlers/rbs/namespace_handler')
+    end
+
     # CRuby Handlers
     # @since 0.8.0
     module C
@@ -170,7 +180,6 @@ module YARD
 
     module Ruby # Ruby parsing components.
       module Legacy # Handles Ruby parsing in Ruby 1.8.
-        autoload :RipperParser,   __p('parser/ruby/legacy/ruby_parser')
         autoload :RubyParser,     __p('parser/ruby/legacy/ruby_parser')
         autoload :RubyToken,      __p('parser/ruby/legacy/ruby_lex')
         autoload :Statement,      __p('parser/ruby/legacy/statement')
@@ -180,9 +189,16 @@ module YARD
 
       autoload :AstNode,           __p('parser/ruby/ast_node')
       autoload :RubyParser,        __p('parser/ruby/ruby_parser')
+      autoload :RipperParser,      __p('parser/ruby/ruby_parser')
       autoload :TokenResolver,     __p('parser/ruby/token_resolver')
     end
 
+    # RBS type signature parser
+    module RBS
+      autoload :RbsParser, __p('parser/rbs/rbs_parser')
+      autoload :Statement, __p('parser/rbs/statement')
+    end
+
     autoload :Base,                __p('parser/base')
     autoload :ParserSyntaxError,   __p('parser/source_parser')
     autoload :SourceParser,        __p('parser/source_parser')
@@ -236,6 +252,7 @@ module YARD
     autoload :FinishRequest,          __p('server/adapter')
     autoload :LibraryVersion,         __p('server/library_version')
     autoload :NotFoundError,          __p('server/adapter')
+    autoload :HTTPUtils,              __p('server/http_utils')
     autoload :RackAdapter,            __p('server/rack_adapter')
     autoload :RackMiddleware,         __p('server/rack_adapter')
     autoload :Router,                 __p('server/router')
@@ -270,6 +287,7 @@ module YARD
   module Templates
     module Helpers # Namespace for template helpers
       module Markup # Namespace for markup providers
+        autoload :HybridMarkdown,           __p('templates/helpers/markup/hybrid_markdown')
         autoload :RDocMarkup,               __p('templates/helpers/markup/rdoc_markup')
         autoload :RDocMarkdown,             __p('templates/helpers/markup/rdoc_markdown')
       end
@@ -297,6 +315,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/cli/command.rb

@@ -70,7 +70,7 @@ module YARD
         load(file)
       rescue LoadError => load_exception
         log.error "The file `#{file}' could not be loaded:\n#{load_exception}"
-        exit
+        exit 1
       end
 
       # Callback when an unrecognize option is parsed

data/lib/yard/cli/diff.rb

@@ -2,6 +2,7 @@
 require 'tmpdir'
 require 'fileutils'
 require 'open-uri'
+require 'open3'
 
 module YARD
   module CLI
@@ -108,7 +109,11 @@ module YARD
         FileUtils.mkdir_p(tmpdir)
         FileUtils.cp_r('.', tmpdir)
         Dir.chdir(tmpdir)
-        log.info("git says: " + `git reset --hard #{commit}`.chomp)
+        out, status = Open3.capture2e('git', 'reset', '--hard', commit)
+        log.info("git says: " + out.chomp)
+        unless status.success?
+          raise "git reset --hard #{commit.inspect} failed with exit status #{status.exitstatus}: #{out}"
+        end
         generate_yardoc(tmpdir)
       ensure
         Dir.chdir(@old_path)
@@ -158,7 +163,7 @@ module YARD
         end
 
         # Remote gemfile from rubygems.org
-        url = "http://rubygems.org/downloads/#{gemfile}"
+        url = "https://rubygems.org/downloads/#{gemfile}"
         log.info "Searching for remote gem file #{url}"
         begin
           # Note: In Ruby 2.4.x, URI.open is a private method. After

data/lib/yard/cli/yardoc.rb

@@ -334,7 +334,7 @@ module YARD
       private
 
       # Generates output for objects
-      # @param [Hash, nil] checksums if supplied, a list of checkums for files.
+      # @param [Hash, nil] checksums if supplied, a list of checksums for files.
       # @return [void]
       # @since 0.5.1
       def run_generate(checksums)

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.
@@ -303,6 +303,7 @@ module YARD
       # definitions with docstrings first.
       #
       # @return [String] a filename
+      # @return [nil] if there is no file associated with the object
       def file
         @files.first ? @files.first[0] : nil
       end
@@ -434,7 +435,10 @@ module YARD
       #
       # @return [Symbol] the type of code object this represents
       def type
-        self.class.name.split('::').last.gsub(/Object$/, '').downcase.to_sym
+        obj_name = self.class.name.split('::').last
+        obj_name.gsub!(/Object$/, '')
+        obj_name.downcase!
+        obj_name.to_sym
       end
 
       # Represents the unique path of the object. The default implementation

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/code_objects/proxy.rb

@@ -201,7 +201,7 @@ module YARD
 
       private
 
-      # @note this method fixes a bug in 1.9.2: http://gist.github.com/437136
+      # @note this method fixes a bug in 1.9.2: https://gist.github.com/437136
       def to_ary; nil end
 
       # Attempts to find the object that this unresolved object

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
@@ -8,7 +7,7 @@ module YARD
   #
   # == Subclassing Notes
   #
-  # The DocstringParser can be subclassed and subtituted during parsing by
+  # The DocstringParser can be subclassed and substituted during parsing by
   # setting the {Docstring.default_parser} attribute with the name of the
   # subclass. This allows developers to change the way docstrings are
   # parsed, allowing for completely different docstring syntaxes.

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
@@ -36,6 +35,7 @@ module YARD
       register_handler_namespace :ruby, Ruby
       register_handler_namespace :ruby18, Ruby::Legacy
       register_handler_namespace :c, C
+      register_handler_namespace :rbs, RBS
 
       # @return [String] the filename
       attr_accessor :file

data/lib/yard/handlers/rbs/attribute_handler.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# Handles RBS attr_reader, attr_writer, and attr_accessor declarations.
+#
+# Registers one or two {YARD::CodeObjects::MethodObject} instances (reader
+# and/or writer) with @return / @param tags derived from the RBS type.
+class YARD::Handlers::RBS::AttributeHandler < YARD::Handlers::RBS::Base
+  handles :attr_reader, :attr_writer, :attr_accessor
+
+  process do
+    attr_name  = statement.name
+    rbs_type   = statement.attr_rbs_type
+    yard_types = rbs_type ? YARD::Handlers::RBS::MethodHandler.rbs_type_to_yard_types(rbs_type) : nil
+    mscope     = statement.visibility == :class ? :class : :instance
+
+    case statement.type
+    when :attr_reader
+      register_reader(attr_name, yard_types, mscope)
+      register_existing_attribute_method(attr_name, "#{attr_name}=", :write, mscope)
+    when :attr_writer
+      register_existing_attribute_method(attr_name, attr_name, :read, mscope)
+      register_writer(attr_name, yard_types, mscope)
+    when :attr_accessor
+      register_reader(attr_name, yard_types, mscope)
+      register_writer(attr_name, yard_types, mscope)
+    end
+  end
+
+  private
+
+  def register_reader(name, types, scope)
+    obj = MethodObject.new(namespace, name, scope)
+    obj.source ||= "def #{name}\n  @#{name}\nend"
+    obj.signature ||= "def #{name}"
+    obj = register(obj)
+    obj.docstring = "Returns the value of attribute #{name}." if obj.docstring.blank?(false)
+    apply_tag_types(obj, :return, types)
+    namespace.attributes[obj.scope][name] ||= SymbolHash[:read => nil, :write => nil]
+    namespace.attributes[obj.scope][name][:read] = obj
+    obj
+  end
+
+  def register_writer(name, types, scope)
+    obj = MethodObject.new(namespace, "#{name}=", scope)
+    obj.parameters = [['value', nil]]
+    obj.source ||= "def #{name}=(value)\n  @#{name} = value\nend"
+    obj.signature ||= "def #{name}=(value)"
+    obj = register(obj)
+    obj.docstring = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to." if obj.docstring.blank?(false)
+    apply_tag_types(obj, :param, types, "value")
+    namespace.attributes[obj.scope][name] ||= SymbolHash[:read => nil, :write => nil]
+    namespace.attributes[obj.scope][name][:write] = obj
+    obj
+  end
+
+  def register_existing_attribute_method(attr_name, meth_name, type, scope)
+    namespace.attributes[scope][attr_name] ||= SymbolHash[:read => nil, :write => nil]
+    return if namespace.attributes[scope][attr_name][type]
+
+    obj = namespace.children.find do |other|
+      other.name == meth_name.to_sym && other.scope == scope
+    end
+
+    namespace.attributes[scope][attr_name][type] = obj if obj
+  end
+
+  def apply_tag_types(obj, tag_name, types, tag_param_name = nil)
+    return unless types
+
+    tag = obj.tags(tag_name).find do |existing_tag|
+      existing_tag.name == tag_param_name
+    end
+
+    if tag
+      tag.types ||= types
+    else
+      obj.add_tag YARD::Tags::Tag.new(tag_name, '', types, tag_param_name)
+    end
+  end
+end

data/lib/yard/handlers/rbs/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+module YARD
+  module Handlers
+    # Handlers for RBS (Ruby type signature) files.
+    module RBS
+      # Base class for all RBS handlers.
+      # Handlers match on the {Parser::RBS::Statement#type} symbol of the
+      # current statement and process it to create or annotate code objects.
+      class Base < Handlers::Base
+        # @return [Boolean] whether this handler matches the given statement
+        def self.handles?(statement, _processor)
+          handlers.any? do |matcher|
+            case matcher
+            when Symbol
+              statement.type == matcher
+            when String
+              statement.type.to_s == matcher
+            when Regexp
+              (statement.source || '') =~ matcher
+            else
+              false
+            end
+          end
+        end
+
+        # Recurse into the body of a namespace statement.
+        # @param opts [Hash] state overrides
+        # @see #push_state
+        def parse_block(opts = {})
+          return if statement.block.nil? || statement.block.empty?
+          push_state(opts) do
+            parser.process(statement.block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/rbs/constant_handler.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# Handles RBS constant declarations: `Name: Type`
+class YARD::Handlers::RBS::ConstantHandler < YARD::Handlers::RBS::Base
+  handles :constant
+
+  process do
+    obj = register ConstantObject.new(namespace, statement.name)
+    if statement.attr_rbs_type && !obj.has_tag?(:return)
+      obj.add_tag YARD::Tags::Tag.new(:return, '', rbs_types(statement.attr_rbs_type))
+    end
+  end
+
+  private
+
+  def rbs_types(type_str)
+    YARD::Handlers::RBS::MethodHandler.rbs_type_to_yard_types(type_str)
+  end
+end