rdoc 6.14.2 → 6.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff34d02bfaa6b5e36bd3ab29b6fdfc10e41a50ba0fbef3841aed3e59d22e8d29
-  data.tar.gz: bee9f682708babef768b5fe0b5b68a505ad09ba255c20c00fdefb52cd5135566
+  metadata.gz: ed79e2cda1c5cd7113829e3fcfbbece5c1d5332e9046778c2581d28059afd9e7
+  data.tar.gz: cc77a3249231ee94df7d06090d9a683e0c7f71f5924186e2f0dcae5b01ec5b74
 SHA512:
-  metadata.gz: 10729c09826000d5ac6d4137fdba80b36dd7da96c66475ee03fcfe527dd159a74f41ec8c1a5cb588373c4007ea02a18cd9ca5e09e1766125daab7e84ca17a6ae
-  data.tar.gz: 785c69b91032d0e72810f91c56271d100d03439355bda96f808faaea60ec2768caab376a8420bbbb72e7bbeb6c50a06ed5a002c668342aa80444ee7d0b1c2a6f
+  metadata.gz: 43bd516f9ffb4f33e76c6186c8b0429525d4729172a25de895a2f1d69f7c523bdc8868c42dc55dc17863f6daa927a56d1aaefbb9edc5519a4885f2a5b60e0cbf
+  data.tar.gz: 368780ba1a40869aa6a26e2a5734d13bb5ec25e4d47dcea78cb0de2c117bad7b8e964ea69b857aadc799f492f72d51a7d68a7259f357c2d23c9a13064c33ce3b

data/README.md

@@ -0,0 +1,112 @@
+# RDoc - Ruby Documentation System
+
+- GitHub: [https://github.com/ruby/rdoc](https://github.com/ruby/rdoc)
+- Issues: [https://github.com/ruby/rdoc/issues](https://github.com/ruby/rdoc/issues)
+
+## Description
+
+RDoc produces HTML and command-line documentation for Ruby projects.  RDoc includes the `rdoc` and `ri` tools for generating and displaying documentation from the command-line.
+
+## Generating Documentation
+
+Once installed, you can create documentation using the `rdoc` command
+
+```shell
+rdoc [options] [names...]
+```
+
+For an up-to-date option summary, type
+
+```shell
+rdoc --help
+```
+
+A typical use might be to generate documentation for a package of Ruby source (such as RDoc itself).
+
+```shell
+rdoc
+```
+
+This command generates documentation for all the Ruby and C source files in and below the current directory.  These will be stored in a documentation tree starting in the subdirectory `doc`.
+
+You can make this slightly more useful for your readers by having the index page contain the documentation for the primary file.  In our case, we could type
+
+```shell
+rdoc --main README.md
+```
+
+You'll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.
+
+RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C and Ruby source files only.
+
+To generate documentation using `rake` see [RDoc::Task](https://ruby.github.io/rdoc/RDoc/Task.html).
+
+To generate documentation programmatically:
+
+```rb
+require 'rdoc/rdoc'
+
+options = RDoc::Options.new
+options.files = ['a.rb', 'b.rb']
+options.setup_generator 'darkfish'
+# see RDoc::Options
+
+rdoc = RDoc::RDoc.new
+rdoc.document options
+# see RDoc::RDoc
+```
+
+You can specify the target files for document generation with `.document` file in the project root directory. `.document` file contains a list of file and directory names including comment lines starting with `#`. See [https://github.com/ruby/rdoc/blob/master/.document](https://github.com/ruby/rdoc/blob/master/.document) as an example.
+
+## Writing Documentation
+
+To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:
+
+```rb
+##
+# This class represents an arbitrary shape by a series of points.
+class Shape
+  ##
+  # Creates a new shape described by a +polyline+.
+  #
+  # If the +polyline+ does not end at the same point it started at the
+  # first pointed is copied and placed at the end of the line.
+  #
+  # An ArgumentError is raised if the line crosses itself, but shapes may
+  # be concave.
+  def initialize polyline
+    # ...
+  end
+end
+```
+
+The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported.  You can set the default comment format for your entire project by creating a `.rdoc_options` file.  See RDoc::Options@Saved+Options for instructions on creating one.  You can also set the comment format for a single file through the `:markup:` directive, but this is only recommended if you wish to switch markup formats.  See RDoc::Markup@Other+directives.
+
+Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing.  See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic.  See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
+
+See RDoc::Parser::C for documenting C extensions with RDoc.
+
+To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report.  `rdoc -C1 lib` includes parameter names in the documentation coverage report.
+
+## Theme Options
+
+There are a few community-maintained themes for RDoc:
+
+- [rorvswild-theme-rdoc](https://github.com/BaseSecrete/rorvswild-theme-rdoc)
+- [hanna](https://github.com/jeremyevans/hanna) (a fork maintained by [Jeremy Evans](https://github.com/jeremyevans))
+
+Please follow the theme's README for usage instructions.
+
+## Bugs
+
+See CONTRIBUTING.rdoc for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.
+
+## License
+
+RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. Portions (c) 2007-2011 Eric Hodel.  Portions copyright others, see individual files and LEGAL.rdoc for details.
+
+RDoc is free software, and may be redistributed under the terms specified in LICENSE.rdoc.
+
+## Warranty
+
+This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.

data/RI.md

@@ -48,7 +48,7 @@ the [Ruby online documentation](https://docs.ruby-lang.org/en/master):
 - If you are working in a terminal window, typing `ri _whatever_` (or just `ri`)
   may be faster than navigating to a browser window and searching for documentation.
 - If you are working in an
-  [irb \(interactive Ruby\)](https://docs.ruby-lang.org/en/master/IRB.html)
+  [irb \(interactive Ruby\)](https://ruby.github.io/irb/index.html)
   session, you _already_ have immediate access to `ri`:
   just type `'show_doc'`.
 

data/lib/rdoc/code_object/top_level.rb

@@ -114,14 +114,6 @@ class RDoc::TopLevel < RDoc::Context
 
   alias name base_name
 
-  ##
-  # Only a TopLevel that contains text file) will be displayed.  See also
-  # RDoc::CodeObject#display?
-
-  def display?
-    text? and super
-  end
-
   ##
   # See RDoc::TopLevel::find_class_or_module
   #--

data/lib/rdoc/cross_reference.rb

@@ -200,7 +200,7 @@ class RDoc::CrossReference
     ref = resolve_method name unless ref
 
     # Try a page name
-    ref = @store.page name if not ref and name =~ /^[\w.]+$/
+    ref = @store.page name if not ref and name =~ /^[\w.\/]+$/
 
     ref = nil if RDoc::Alias === ref # external alias, can't link to it
 

data/lib/rdoc/generator/template/darkfish/_footer.rhtml

@@ -1,5 +1,5 @@
 <footer id="validator-badges" role="contentinfo">
-  <p><a href="https://validator.w3.org/check/referer">Validate</a>
-  <p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> <%= RDoc::VERSION %>.
-  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+  <p><a href="https://validator.w3.org/check/referer">Validate</a></p>
+  <p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> <%= RDoc::VERSION %>.</p>
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.</p>
 </footer>

data/lib/rdoc/generator/template/darkfish/_head.rhtml

@@ -1,34 +1,34 @@
 <meta charset="<%= @options.charset %>">
-<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="viewport" content="width=device-width, initial-scale=1">
 
 <title><%= h @title %></title>
 
-<%- if defined?(klass) -%>
+<%- if defined?(klass) %>
   <meta name="keywords" content="ruby,<%= h "#{klass.type},#{klass.full_name}" %>">
 
-  <%- if klass.comment.empty? -%>
+  <%- if klass.comment.empty? %>
     <meta name="description" content="Documentation for the <%= h "#{klass.full_name} #{klass.type}" %>">
-  <%- else -%>
+  <%- else %>
     <meta name="description" content="<%= h "#{klass.type} #{klass.full_name}: #{excerpt(klass.comment)}" %>">
-  <%- end -%>
-<%- elsif defined?(file) -%>
+  <%- end %>
+<%- elsif defined?(file) %>
   <meta name="keywords" content="ruby,documentation,<%= h file.page_name %>">
   <meta name="description" content="<%= h "#{file.page_name}: #{excerpt(file.comment)}" %>">
-<%- elsif @title -%>
+<%- elsif @title %>
   <meta name="keywords" content="ruby,documentation,<%= h @title %>">
 
   <%- if @options.main_page and
       main_page = @files.find { |f| f.full_name == @options.main_page } then %>
     <meta name="description" content="<%= h "#{@title}: #{excerpt(main_page.comment)}" %>">
-  <%- else -%>
+  <%- else %>
     <meta name="description" content="Documentation for <%= h @title %>">
-  <%- end -%>
-<%- end -%>
+  <%- end %>
+<%- end %>
 
-<%- if canonical_url = @options.canonical_root -%>
+<%- if canonical_url = @options.canonical_root %>
 <% canonical_url = current.canonical_url if defined?(current) %>
 <link rel="canonical" href="<%= canonical_url %>">
-<%- end -%>
+<%- end %>
 
 <script type="text/javascript">
   var rdoc_rel_prefix = "<%= h asset_rel_prefix %>/";
@@ -43,6 +43,6 @@
 
 <link href="<%= h asset_rel_prefix %>/css/fonts.css" rel="stylesheet">
 <link href="<%= h asset_rel_prefix %>/css/rdoc.css" rel="stylesheet">
-<%- @options.template_stylesheets.each do |stylesheet| -%>
+<%- @options.template_stylesheets.each do |stylesheet| %>
 <link href="<%= h asset_rel_prefix %>/<%= File.basename stylesheet %>" rel="stylesheet">
-<%- end -%>
+<%- end %>

data/lib/rdoc/generator/template/darkfish/_sidebar_extends.rhtml

@@ -3,13 +3,13 @@
   <h3>Extended With Modules</h3>
 
   <ul class="link-list">
-    <%- klass.extends.each do |ext| -%>
-  <%- unless String === ext.module then -%>
-    <li><a class="extend" href="<%= klass.aref_to ext.module.path %>"><%= ext.module.full_name %></a>
-  <%- else -%>
-    <li><span class="extend"><%= ext.name %></span>
-  <%- end -%>
-  <%- end -%>
+  <%- klass.extends.each do |ext| %>
+  <%- unless String === ext.module then %>
+    <li><a class="extend" href="<%= klass.aref_to ext.module.path %>"><%= ext.module.full_name %></a></li>
+  <%- else %>
+    <li><span class="extend"><%= ext.name %></span></li>
+  <%- end %>
+  <%- end %>
   </ul>
 </div>
-<%- end -%>
+<%- end %>

data/lib/rdoc/generator/template/darkfish/_sidebar_includes.rhtml

@@ -3,13 +3,13 @@
   <h3>Included Modules</h3>
 
   <ul class="link-list">
-  <%- klass.includes.each do |inc| -%>
-  <%- unless String === inc.module then -%>
-    <li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a>
-  <%- else -%>
-    <li><span class="include"><%= inc.name %></span>
-  <%- end -%>
-  <%- end -%>
+  <%- klass.includes.each do |inc| %>
+  <%- unless String === inc.module then %>
+    <li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a></li>
+  <%- else %>
+    <li><span class="include"><%= inc.name %></span></li>
+  <%- end %>
+  <%- end %>
   </ul>
 </div>
-<%- end -%>
+<%- end %>

data/lib/rdoc/generator/template/darkfish/_sidebar_installed.rhtml

@@ -2,14 +2,15 @@
   <h3>Documentation</h3>
 
   <ul>
-  <%- installed.each do |name, href, exists, type, _| -%>
-    <%- next if type == :extra -%>
+  <%- installed.each do |name, href, exists, type, _| %>
+    <%- next if type == :extra %>
     <li class="folder">
-    <%- if exists then -%>
+    <%- if exists then %>
       <a href="<%= href %>"><%= h name %></a>
-    <%- else -%>
+    <%- else %>
       <%= h name %>
-    <%- end -%>
-  <%- end -%>
+    <%- end %>
+    </li>
+  <%- end %>
   </ul>
 </div>

data/lib/rdoc/generator/template/darkfish/_sidebar_methods.rhtml

@@ -2,9 +2,9 @@
   <div class="nav-section">
     <h3>Class Methods</h3>
     <ul class="link-list" role="directory">
-      <%- class_methods.each do |meth| -%>
-      <li <%- if meth.calls_super %>class="calls-super" <%- end %>><a href="#<%= meth.aref %>"><%= h meth.name -%></a></li>
-      <%- end -%>
+      <%- class_methods.each do |meth| %>
+      <li <%- if meth.calls_super %>class="calls-super" <%- end %>><a href="#<%= meth.aref %>"><%= h meth.name %></a></li>
+      <%- end %>
     </ul>
   </div>
 <% end %>
@@ -13,9 +13,9 @@
   <div class="nav-section">
     <h3>Instance Methods</h3>
     <ul class="link-list" role="directory">
-      <%- instance_methods.each do |meth| -%>
-      <li <%- if meth.calls_super %>class="calls-super" <%- end %>><a href="#<%= meth.aref %>"><%= h meth.name -%></a></li>
-      <%- end -%>
+      <%- instance_methods.each do |meth| %>
+      <li <%- if meth.calls_super %>class="calls-super" <%- end %>><a href="#<%= meth.aref %>"><%= h meth.name %></a></li>
+      <%- end %>
     </ul>
   </div>
 <% end %>

data/lib/rdoc/generator/template/darkfish/_sidebar_pages.rhtml

@@ -1,32 +1,32 @@
 <%- simple_files = @files.select { |f| f.text? } %>
-<%- if defined?(current) -%>
-  <%- dir = current.full_name[%r{\A[^/]+(?=/)}] || current.page_name -%>
-<%- end -%>
-<%- unless simple_files.empty? then -%>
+<%- if defined?(current) %>
+  <%- dir = current.full_name[%r{\A[^/]+(?=/)}] || current.page_name %>
+<%- end %>
+<%- unless simple_files.empty? then %>
 <div id="fileindex-section" class="nav-section">
   <h3>Pages</h3>
 
   <ul class="link-list">
-  <%- simple_files.group_by do |f| -%>
-    <%- f.full_name[%r{\A[^/]+(?=/)}] || f.page_name -%>
-  <%- end.each do |n, files| -%>
-    <%- f = files.shift -%>
-    <%- if files.empty? -%>
-    <li><a href="<%= rel_prefix %>/<%= h f.path %>"><%= h f.page_name %></a>
-      <%- next -%>
-    <%- end -%>
-    <li><details<% if dir == n %> open<% end %>><summary><%
+  <%- simple_files.group_by do |f|
+    f.full_name[%r{\A[^/]+(?=/)}] || f.page_name
+  end.each do |n, files| %>
+    <%- f = files.shift %>
+    <%- if files.empty? %>
+    <li><a href="<%= rel_prefix %>/<%= h f.path %>"><%= h f.page_name %></a></li>
+      <%- next %>
+    <%- end %>
+    <li><details<%= ' open' if dir == n %>><summary><%
     if n == f.page_name
       %><a href="<%= rel_prefix %>/<%= h f.path %>"><%= h n %></a><%
     else
       %><%= h n %><% files.unshift(f)
     end %></summary>
     <ul class="link-list">
-    <%- files.each do |f| -%>
-      <li><a href="<%= rel_prefix %>/<%= h f.path %>"><%= h f.page_name %></a>
-    <%- end -%>
-    </ul></details>
-  <%- end -%>
+    <%- files.each do |f| %>
+      <li><a href="<%= rel_prefix %>/<%= h f.path %>"><%= h f.page_name %></a></li>
+    <%- end %>
+    </ul></details></li>
+  <%- end %>
   </ul>
 </div>
-<%- end -%>
+<%- end %>

data/lib/rdoc/generator/template/darkfish/_sidebar_parent.rhtml

@@ -1,6 +1,6 @@
-<%- if klass.type == 'class' && (ancestors = klass.super_classes).any? -%>
+<%- if klass.type == 'class' && (ancestors = klass.super_classes).any? %>
 <div id="parent-class-section" class="nav-section">
   <h3>Ancestors</h3>
   <%= generate_ancestor_list(ancestors, klass) %>
 </div>
-<%- end -%>
+<%- end %>

data/lib/rdoc/generator/template/darkfish/_sidebar_sections.rhtml

@@ -3,9 +3,9 @@
   <h3>Sections</h3>
 
   <ul class="link-list" role="directory">
-    <%- klass.sort_sections.each do |section| -%>
+    <%- klass.sort_sections.each do |section| %>
       <li><a href="#<%= section.aref %>"><%= h section.title %></a></li>
-    <%- end -%>
+    <%- end %>
   </ul>
 </div>
-<%- end -%>
+<%- end %>

data/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml

@@ -9,31 +9,31 @@
 <div class="nav-section">
   <h3>Table of Contents</h3>
 
-    <%- display_link = proc do |heading| -%>
+    <%- display_link = proc do |heading| %>
       <a href="#<%= heading.label current %>"><%= heading.plain_html %></a>
-    <%- end -%>
+    <%- end %>
 
-    <%- list_siblings = proc do -%>
-      <%- level = table.first&.level -%>
-      <%- while table.first && table.first.level >= level -%>
-        <%- heading = table.shift -%>
-        <%- if table.first.nil? || table.first.level <= heading.level -%>
-          <li><% display_link.call heading -%>
-        <%- else -%>
+    <%- list_siblings = proc do %>
+      <%- level = table.first&.level %>
+      <%- while table.first && table.first.level >= level %>
+        <%- heading = table.shift %>
+        <%- if table.first.nil? || table.first.level <= heading.level %>
+          <li><% display_link.call heading %></li>
+        <%- else %>
           <li>
             <details open>
-              <summary><%- display_link.call heading -%></summary>
+              <summary><%- display_link.call heading %></summary>
               <ul class="link-list" role="directory">
                 <% list_siblings.call %>
               </ul>
             </details>
           </li>
-        <%- end -%>
-      <%- end -%>
-    <%- end -%>
+        <%- end %>
+      <%- end %>
+    <%- end %>
 
   <ul class="link-list" role="directory">
     <% list_siblings.call %>
   </ul>
 </div>
-<%- end -%>
+<%- end %>