boondoc 0.1.0 → 0.2.0

data/lib/boondoc/frontend/visitor.rb

@@ -20,7 +20,7 @@ module Boondoc
       }.freeze
       ALWAYS_PRIVATE = %w[initialize_copy initialize_clone initialize_dup respond_to_missing?].freeze
       ATTR_READERS_ONLY = %i[attr attr_reader].freeze
-      ANONYMOUS = { 'Struct' => :new, 'Data' => :define, 'Class' => :new, 'Module' => :new }.freeze
+      ANONYMOUS = { "Struct" => :new, "Data" => :define, "Class" => :new, "Module" => :new }.freeze
 
       # @param registry [Model::Registry]
       # @param file [String] file name recorded on each object
@@ -126,7 +126,7 @@ module Boondoc
       end
 
       def ensure_namespace(name, kind)
-        parts = name.delete_prefix('::').split('::')
+        parts = name.delete_prefix("::").split("::")
         parent = namespace_base(name, parts)
         parts.each_with_index do |part, index|
           last = index == parts.size - 1
@@ -139,7 +139,7 @@ module Boondoc
       # the namespace that already holds the first segment for `Foo::Bar`, and
       # the current namespace otherwise.
       def namespace_base(name, parts)
-        return @registry.root if name.start_with?('::')
+        return @registry.root if name.start_with?("::")
         return frame.namespace if parts.size == 1
 
         @registry.resolve(frame.namespace, parts.first)&.namespace || frame.namespace
@@ -158,13 +158,13 @@ module Boondoc
 
       def anonymous_namespace?(value)
         value.is_a?(::Prism::CallNode) && value.receiver &&
-          ANONYMOUS[value.receiver.slice.delete_prefix('::')] == value.name
+          ANONYMOUS[value.receiver.slice.delete_prefix("::")] == value.name
       end
 
       # `Foo = Struct.new(:a)`, `Foo = Data.define(:a)`, `Foo = Class.new(Base)`
       def define_anonymous(node, value)
-        receiver = value.receiver.slice.delete_prefix('::')
-        namespace = ensure_namespace(node.name.to_s, receiver == 'Module' ? :module : :class)
+        receiver = value.receiver.slice.delete_prefix("::")
+        namespace = ensure_namespace(node.name.to_s, (receiver == "Module") ? :module : :class)
         namespace.superclass ||= anonymous_superclass(receiver, value)
         document(namespace, line(node))
         with_frame(namespace) do
@@ -175,7 +175,7 @@ module Boondoc
 
       def anonymous_superclass(receiver, value)
         return receiver if %w[Struct Data].include?(receiver)
-        return nil unless receiver == 'Class'
+        return nil unless receiver == "Class"
 
         first = arguments(value).first
         first.slice if first.is_a?(::Prism::ConstantReadNode) || first.is_a?(::Prism::ConstantPathNode)
@@ -186,7 +186,7 @@ module Boondoc
 
         arguments(value).grep(::Prism::SymbolNode).each do |member|
           add_method(member.unescaped, :instance, line, attribute: :reader, documented: false)
-          next if receiver == 'Data'
+          next if receiver == "Data"
 
           add_method("#{member.unescaped}=", :instance, line, attribute: :writer, documented: false)
         end
@@ -196,7 +196,7 @@ module Boondoc
 
       def def_scope(node)
         case node.receiver
-        when nil then frame.singleton || frame.module_function ? :class : :instance
+        when nil then (frame.singleton || frame.module_function) ? :class : :instance
         when ::Prism::SelfNode then :class
         else :class if [frame.namespace.name, frame.namespace.path].include?(node.receiver.slice)
         end
@@ -258,7 +258,7 @@ module Boondoc
       end
 
       def on_class_visibility(node)
-        visibility = node.name == :private_class_method ? :private : :public
+        visibility = (node.name == :private_class_method) ? :private : :public
         apply_visibility(arguments(node), visibility, :class)
       end
 
@@ -323,7 +323,7 @@ module Boondoc
       end
 
       def on_mixin(node)
-        kind = frame.singleton && node.name == :include ? :extend : node.name
+        kind = (frame.singleton && node.name == :include) ? :extend : node.name
         arguments(node).each do |arg|
           next unless arg.is_a?(::Prism::ConstantReadNode) || arg.is_a?(::Prism::ConstantPathNode)
 

data/lib/boondoc/generator.rb

@@ -25,7 +25,7 @@ module Boondoc
     def run
       report_config
       files = @config.source_files
-      raise Error, "no Ruby files matched #{Array(@config.sources).join(', ')}" if files.empty?
+      raise Error, "no Ruby files matched #{Array(@config.sources).join(", ")}" if files.empty?
 
       parse(files)
       pages = render
@@ -71,8 +71,10 @@ module Boondoc
         merge_yard(files & @registry.directive_files)
       elsif @registry.directive_sites.any?
         sites = @registry.directive_sites
-        @reporter.warn("#{sites.size} comment(s) use YARD directives (@!macro, @!method, ...), which boondoc " \
-                       "does not expand on its own; rerun with --yard-macros. First: #{sites.first(3).join(', ')}")
+        @reporter.warn(
+          "#{sites.size} comment(s) use YARD directives (@!macro, @!method, ...), which boondoc " \
+          "does not expand on its own; rerun with --yard-macros. First: #{sites.first(3).join(", ")}"
+        )
       end
     end
 
@@ -81,8 +83,10 @@ module Boondoc
       @reporter.info("yard: added #{added} object(s) from macros and directives")
       return unless yard_files.empty?
 
-      @reporter.warn('yard: no YARD macros or directives were found; disable yard_macros ' \
-                     '(--yard-macros) for this project')
+      @reporter.warn(
+        "yard: no YARD macros or directives were found; disable yard_macros " \
+        "(--yard-macros) for this project"
+      )
     end
 
     def pages_for(context)
@@ -100,14 +104,16 @@ module Boondoc
     def namespace_pages(context)
       namespaces = @registry.grep(Model::NamespaceObject).select { |namespace| context.filter.visible?(namespace) }
       namespaces.to_h { |namespace| [namespace, Renderer::NamespacePage.new(context, namespace)] }
-                .select { |_, page| page.content? }
+        .select { |_, page| page.content? }
     end
 
     def finish(pages, assets, removed)
       warnings = @reporter.warnings
-      @reporter.info("boondoc: wrote #{pages.size} file(s) and #{assets.size} asset(s) to #{@config.output}" \
-                     "#{", removed #{removed.size} stale" if removed.any?}" \
-                     "#{", #{warnings.size} warning(s)" if warnings.any?}")
+      @reporter.info(
+        "boondoc: wrote #{pages.size} file(s) and #{assets.size} asset(s) to #{@config.output}" \
+        "#{", removed #{removed.size} stale" if removed.any?}" \
+        "#{", #{warnings.size} warning(s)" if warnings.any?}"
+      )
       raise Error, "#{warnings.size} warning(s) in strict mode" if @config.strict && warnings.any?
 
       Result.new(pages: pages.keys.sort, assets: assets.keys.sort, removed: removed, warnings: warnings)

data/lib/boondoc/linker.rb

@@ -6,7 +6,7 @@ module Boondoc
   # Handles `{Foo#bar}`, `{Foo#bar custom text}`, `{https://example.com text}`,
   # `{file:GUIDE.md}`, and the include forms `{include:Foo}` and
   # `{include:file:path.md}`. Code blocks and code spans are left untouched.
-  class Linker # rubocop:disable Metrics/ClassLength -- references and asset links resolved in one place
+  class Linker
     REFERENCE = /(?<escape>\\)?\{(?<target>[^{}\s]+)(?:\s+(?<title>[^{}]+?))?\}/
     INCLUDE = /\{include:(?<file>file:)?(?<target>[^{}\s]+)\}/
     URL = %r{\A(?:[a-z][a-z0-9+.-]*://|mailto:)}i
@@ -69,13 +69,13 @@ module Boondoc
     def types(types, object:, from:)
       return nil if types.nil? || types.empty?
 
-      types.map { |type| type_markup(type, object, from) }.join(', ')
+      types.map { |type| type_markup(type, object, from) }.join(", ")
     end
 
     private
 
     def expand_includes(text, object, depth)
-      return text if depth > MAX_INCLUDE_DEPTH || !text.include?('{include:')
+      return text if depth > MAX_INCLUDE_DEPTH || !text.include?("{include:")
 
       Markdown.map_prose(text) do |prose|
         prose.gsub(INCLUDE) { included(Regexp.last_match, object, depth) }
@@ -101,10 +101,10 @@ module Boondoc
     def reference(match, object, from)
       target = match[:target]
       title = match[:title]&.strip
-      return match[0].delete_prefix('\\') if match[:escape]
-      return match[0] if target.start_with?('include:')
+      return match[0].delete_prefix("\\") if match[:escape]
+      return match[0] if target.start_with?("include:")
       return "[#{title || target}](#{target})" if URL.match?(target)
-      return file_reference(match, target.delete_prefix('file:'), title, from) if target.start_with?('file:')
+      return file_reference(match, target.delete_prefix("file:"), title, from) if target.start_with?("file:")
 
       object_reference(match, title, object, from)
     end
@@ -147,11 +147,11 @@ module Boondoc
 
     # References to Ruby's own classes cannot be linked, but are not mistakes.
     def core?(target)
-      CORE_CONSTANTS.include?(target.delete_prefix('::')[/\A[A-Z]\w*/])
+      CORE_CONSTANTS.include?(target.delete_prefix("::")[/\A[A-Z]\w*/])
     end
 
     def location(object)
-      object.root? ? 'docs' : object.path
+      object.root? ? "docs" : object.path
     end
 
     def type_markup(type, object, from)

data/lib/boondoc/markdown.rb

@@ -19,13 +19,13 @@ module Boondoc
     # @return [String]
     def map_prose(text, &)
       state = { fence: nil, indented: false, blank: true, list: false }
-      output = +''
-      prose = +''
+      output = +""
+      prose = +""
       text.each_line do |line|
         next prose << line unless code_line?(line, state)
 
         output << map_inline(prose, &) << line
-        prose = +''
+        prose = +""
       end
       output << map_inline(prose, &)
     end
@@ -33,7 +33,7 @@ module Boondoc
     # @param text [String] a single table cell
     # @return [String] the text on one line with pipes escaped
     def table_cell(text)
-      text.gsub(/\s*\n\s*/, ' ').gsub('|', '\\|').strip
+      text.gsub(/\s*\n\s*/, " ").gsub("|", '\\|').strip
     end
 
     # @api private
@@ -58,7 +58,7 @@ module Boondoc
 
     # @api private
     def in_list?(line, blank, state)
-      LIST_ITEM.match?(line) || (state[:list] && (blank || line.start_with?(' ', "\t")))
+      LIST_ITEM.match?(line) || (state[:list] && (blank || line.start_with?(" ", "\t")))
     end
 
     # @api private
@@ -77,7 +77,7 @@ module Boondoc
     def map_inline(prose)
       return prose if prose.empty?
 
-      output = +''
+      output = +""
       position = 0
       prose.scan(INLINE_CODE) do
         match = Regexp.last_match

data/lib/boondoc/model/code_object.rb

@@ -27,7 +27,7 @@ module Boondoc
 
       # @return [String] the fully qualified path, such as `Foo::Bar#baz`
       def path
-        namespace.nil? || namespace.root? ? name : "#{namespace.path}::#{name}"
+        (namespace.nil? || namespace.root?) ? name : "#{namespace.path}::#{name}"
       end
 
       # @return [Boolean]
@@ -46,7 +46,7 @@ module Boondoc
 
       # @return [Boolean] true when tagged `@private` or `@api private`
       def private_api?
-        docstring.tag?('private') || docstring.tags_named('api').any? { |tag| tag.text.strip == 'private' }
+        docstring.tag?("private") || docstring.tags_named("api").any? { |tag| tag.text.strip == "private" }
       end
     end
 
@@ -73,7 +73,7 @@ module Boondoc
 
       # @return [String] empty for the root
       def path
-        root? ? '' : super
+        root? ? "" : super
       end
 
       # @return [Boolean]
@@ -95,7 +95,7 @@ module Boondoc
       # @return [Array<MethodObject>] methods in that scope, `initialize` first, then by name
       def meths(scope)
         children.grep(MethodObject).select { |meth| meth.scope == scope }
-                .sort_by { |meth| [meth.name == 'initialize' ? 0 : 1, meth.name] }
+          .sort_by { |meth| [(meth.name == "initialize") ? 0 : 1, meth.name] }
       end
     end
 
@@ -129,12 +129,12 @@ module Boondoc
       # @param name [String]
       # @return [String] the path a method with that name and scope would have
       def self.path_for(namespace, scope, name)
-        "#{namespace.path}#{scope == :class ? '.' : '#'}#{name}"
+        "#{namespace.path}#{(scope == :class) ? "." : "#"}#{name}"
       end
 
       # @return [String] `#` for instance methods, `.` for class methods
       def separator
-        scope == :class ? '.' : '#'
+        (scope == :class) ? "." : "#"
       end
 
       # @return [String]
@@ -156,7 +156,7 @@ module Boondoc
       # @param name [String]
       # @param namespace [NamespaceObject]
       # @param value [String]
-      def initialize(name, namespace, value: '')
+      def initialize(name, namespace, value: "")
         super(name, namespace)
         @value = value
       end

data/lib/boondoc/model/docstring.rb

@@ -7,11 +7,20 @@ module Boondoc
     # Which fields are set depends on the tag: `@param` uses `name`, `types` and
     # `text`; `@example` uses `name` as its title; `@option` adds `key` and
     # `default`; `@overload` carries a `signature` and a nested `docstring`.
-    Tag = Struct.new(:tag_name, :name, :types, :text, :key, :default, :signature, :docstring,
-                     keyword_init: true) do
+    Tag = Struct.new(
+      :tag_name,
+      :name,
+      :types,
+      :text,
+      :key,
+      :default,
+      :signature,
+      :docstring,
+      keyword_init: true
+    ) do
       def initialize(**)
         super
-        self.text ||= ''
+        self.text ||= ""
       end
     end
 
@@ -27,7 +36,7 @@ module Boondoc
       # @param text [String]
       # @param tags [Array<Tag>]
       # @param directives [Array<String>]
-      def initialize(text = '', tags = [], directives = [])
+      def initialize(text = "", tags = [], directives = [])
         @text = text
         @tags = tags
         @directives = directives
@@ -59,11 +68,11 @@ module Boondoc
       # @return [String] the first sentence of the first paragraph, on one line;
       #   falls back to the `@return` description when there is no body
       def summary
-        paragraph = text.strip.split(/\n\s*\n/).first.to_s.gsub(/\s*\n\s*/, ' ')
+        paragraph = text.strip.split(/\n\s*\n/).first.to_s.gsub(/\s*\n\s*/, " ")
         return paragraph[/\A.*?[.!?](?=\s|\z)/] || paragraph unless paragraph.empty?
 
-        returned = tag('return')&.text.to_s.lines.first.to_s.strip
-        returned.empty? ? '' : "Returns #{returned}"
+        returned = tag("return")&.text.to_s.lines.first.to_s.strip
+        returned.empty? ? "" : "Returns #{returned}"
       end
     end
   end

data/lib/boondoc/model/registry.rb

@@ -14,14 +14,14 @@ module Boondoc
       attr_reader :directive_sites
 
       def initialize
-        @root = NamespaceObject.new('', nil, kind: :root)
-        @objects = { '' => @root }
+        @root = NamespaceObject.new("", nil, kind: :root)
+        @objects = { "" => @root }
         @directive_sites = []
       end
 
       # @return [Array<String>] the files that contain YARD directives, in the order they were parsed
       def directive_files
-        @directive_sites.map { |site| site.rpartition(':').first }.uniq
+        @directive_sites.map { |site| site.rpartition(":").first }.uniq
       end
 
       # @param path [String]
@@ -119,7 +119,7 @@ module Boondoc
       end
 
       def constant_candidates(start, const)
-        return [const.delete_prefix('::')] if const.start_with?('::')
+        return [const.delete_prefix("::")] if const.start_with?("::")
 
         lexical(start).map { |scope| scope.root? ? const : "#{scope.path}::#{const}" }
       end
@@ -127,7 +127,7 @@ module Boondoc
       def find_method(namespace, sep, meth)
         return nil unless namespace.is_a?(NamespaceObject)
 
-        separators = { '' => %w[# .], '#' => ['#'] }.fetch(sep, ['.'])
+        separators = { "" => %w[# .], "#" => ["#"] }.fetch(sep, ["."])
         ancestors(namespace).each do |ancestor|
           separators.each do |separator|
             found = self["#{ancestor.path}#{separator}#{meth}"]

data/lib/boondoc/path_map.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'pathname'
+require "pathname"
 
 module Boondoc
   # Maps objects to output files and anchors, and computes relative links.
   class PathMap
-    TOP_LEVEL = 'top-level.md'
+    TOP_LEVEL = "top-level.md"
 
     # @param config [Config]
     # @param registry [Model::Registry] consulted for classes and modules whose
@@ -30,7 +30,7 @@ module Boondoc
     # @return [String, nil] the anchor inside its file; nil for namespaces
     def anchor_for(object)
       case object
-      when Model::MethodObject then "method-#{object.scope == :class ? 'c' : 'i'}-#{escape(object.name)}"
+      when Model::MethodObject then "method-#{(object.scope == :class) ? "c" : "i"}-#{escape(object.name)}"
       when Model::ConstantObject then "constant-#{escape(object.name)}"
       end
     end
@@ -43,7 +43,7 @@ module Boondoc
       file = file_for(object)
       return "##{anchor}" if anchor && file == from
 
-      [relative(file, from), anchor].compact.join('#')
+      [relative(file, from), anchor].compact.join("#")
     end
 
     # @param file [String] output file to link to
@@ -71,7 +71,7 @@ module Boondoc
         parts.unshift(segments[namespace])
         namespace = namespace.namespace
       end
-      parts.join('/')
+      parts.join("/")
     end
 
     # The file or directory name of every class and module, worked out once
@@ -93,16 +93,16 @@ module Boondoc
       seen = Hash.new(0)
       group.each do |child|
         count = (seen[child.kind] += 1)
-        names[child] = ["#{child.name}.#{child.kind}", (count if count > 1)].compact.join('-')
+        names[child] = ["#{child.name}.#{child.kind}", (count if count > 1)].compact.join("-")
       end
     end
 
     def escape(name)
-      name.gsub(/[^A-Za-z0-9_]/) { |char| format('-%02X', char.ord) }
+      name.gsub(/[^A-Za-z0-9_]/) { |char| format("-%02X", char.ord) }
     end
 
     def encode(path)
-      path.gsub(' ', '%20')
+      path.gsub(" ", "%20")
     end
   end
 end

data/lib/boondoc/preview.rb

@@ -7,8 +7,8 @@ module Boondoc
   # The previewer resolves links relative to the directory it was started in,
   # so it is always started from inside the output directory.
   class Preview
-    EXTENSION = 'yusukebe/gh-markdown-preview'
-    DEFAULT_HOST = '127.0.0.1'
+    EXTENSION = "yusukebe/gh-markdown-preview"
+    DEFAULT_HOST = "127.0.0.1"
     LOOPBACK_HOSTS = %w[::1 localhost].freeze
     SILENT = { out: File::NULL, err: File::NULL }.freeze
 
@@ -30,7 +30,7 @@ module Boondoc
     # @raise [Error] when the docs, the GitHub CLI, or the extension are missing
     def start
       raise Error, "#{@directory} does not exist; run `boondoc` first to generate the docs" unless docs?
-      raise Error, 'serve needs the GitHub CLI (gh); see https://cli.github.com' unless gh?
+      raise Error, "serve needs the GitHub CLI (gh); see https://cli.github.com" unless gh?
 
       install unless extension?
       warn_exposed unless loopback?
@@ -40,7 +40,7 @@ module Boondoc
     private
 
     def loopback?
-      LOOPBACK_HOSTS.include?(@host) || @host.start_with?('127.')
+      LOOPBACK_HOSTS.include?(@host) || @host.start_with?("127.")
     end
 
     # The extension answers `/__/md?path=` for any path, not only the docs, and
@@ -48,8 +48,8 @@ module Boondoc
     # every file the current user can.
     def warn_exposed
       warn "boondoc: serving on #{@host} exposes the preview to the network. gh markdown-preview will " \
-           'return any file the current user can read, not only the docs. Use the default 127.0.0.1 ' \
-           'unless everyone who can reach this machine is trusted.'
+           "return any file the current user can read, not only the docs. Use the default 127.0.0.1 " \
+           "unless everyone who can reach this machine is trusted."
     end
 
     def docs?
@@ -57,22 +57,22 @@ module Boondoc
     end
 
     def gh?
-      system('gh', '--version', **SILENT) == true
+      system("gh", "--version", **SILENT) == true
     end
 
     def extension?
-      system('gh', 'markdown-preview', '--version', **SILENT) == true
+      system("gh", "markdown-preview", "--version", **SILENT) == true
     end
 
     def install
       manual = "install it with `gh extension install #{EXTENSION}`"
       raise Error, "serve needs the gh markdown-preview extension; #{manual}" unless @confirm_install&.call
-      raise Error, "could not install the extension; #{manual}" unless system('gh', 'extension', 'install', EXTENSION)
+      raise Error, "could not install the extension; #{manual}" unless system("gh", "extension", "install", EXTENSION)
     end
 
     def serve
-      command = ['gh', 'markdown-preview', '--host', @host]
-      command.push('--port', @port.to_s) if @port
+      command = ["gh", "markdown-preview", "--host", @host]
+      command.push("--port", @port.to_s) if @port
       system(*command, chdir: @directory)
     rescue Interrupt
       nil

data/lib/boondoc/rake_task.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'rake'
-require 'rake/tasklib'
-require 'boondoc'
+require "rake"
+require "rake/tasklib"
+require "boondoc"
 
 module Boondoc
   # Defines a Rake task that generates the documentation.
@@ -25,14 +25,14 @@ module Boondoc
       super()
       @name = name
       @options = {}
-      yield self if block_given?
+      yield(self) if block_given?
       define
     end
 
     private
 
     def define
-      desc 'Generate markdown documentation with boondoc'
+      desc("Generate markdown documentation with boondoc")
       task(name) { Generator.new(Config.load(options)).run }
     end
   end

data/lib/boondoc/references.rb

@@ -22,7 +22,7 @@ module Boondoc
     # Targets are expanded before they are copied, so chains such as
     # `(see B)` -> `(see C)` work in any order. A cycle stops at the object
     # already being expanded.
-    def expand_object(object) # rubocop:disable Metrics/MethodLength
+    def expand_object(object)
       return if @visited.key?(object)
 
       @visited[object] = true

data/lib/boondoc/renderer/base.rb

@@ -26,19 +26,19 @@ module Boondoc
       # A fenced Ruby block whose fence is longer than any fence inside the source.
       def ruby(source)
         longest = source.scan(/^\s*(`{3,})/).flatten.map(&:size).max || 2
-        fence = '`' * [3, longest + 1].max
+        fence = "`" * [3, longest + 1].max
         "#{fence}ruby\n#{source}\n#{fence}"
       end
 
       # Joins blocks into a document with exactly one blank line between them.
       def document(blocks)
-        blocks.flatten.compact.map { |block| block.sub(/\A\n+/, '').rstrip }.reject(&:empty?).join("\n\n") << "\n"
+        blocks.flatten.compact.map { |block| block.sub(/\A\n+/, "").rstrip }.reject(&:empty?).join("\n\n") << "\n"
       end
 
       # A one-line summary of an object, with references resolved.
       def summary(object, from)
         text = linker.text(object.docstring.summary, object: object, from: from)
-        text = "**Deprecated.** #{text}".strip if object.docstring.tag?('deprecated')
+        text = "**Deprecated.** #{text}".strip if object.docstring.tag?("deprecated")
         Markdown.table_cell(text)
       end