rdoc 6.14.1 → 6.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a7e93ac9c35220aeef63714f07b7ad32fc23de76e17e92e32a49012e32f304e
-  data.tar.gz: f273ce6acb9a2caf5e663ddfaae80d676a07e2b0e2d7de818218da742ed795d4
+  metadata.gz: 737b80cad7809fc0b20efe70270867bcc3a7f3ae7c5c0e1f818769b8ab40c7cc
+  data.tar.gz: 6754787e054cab04658a068f8e3a2be8cacb1473991d91a330beb0118bf22930
 SHA512:
-  metadata.gz: 5deecbe6a6a8562324936b2c458c45be5565832ec9ff2ac2fb79f6c2dd8d72add9e08c24485eaa7365d5d0628abed02d0d6a198067d64f0217a6789633c7e57e
-  data.tar.gz: 1ca6dad24e4f748fa8863e301c5f87a89b174523eaf62f2ab505845b2f15aaa4e6a7b215c7ff325c198052358ebfd9c206f0b743c2f97da0eff7444c0edacf96
+  metadata.gz: fad664b000fbb058f96f2e7f032ba767b86213a21380cf584d30ff34710acc5c383bc5053b2a06e3e7190c9f4188d397ba7bc9be226d82231fd2bad76c046258
+  data.tar.gz: 5afe676ff848a49515c6fba65fc5e8a4b765c5e52af6c0128caa36a7a1253a41fc3ac0b0ef2098f74fd69269e285c8d3ec67128cc631b60c97062c5c9fe7cbc0

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/js/darkfish.js

@@ -72,10 +72,30 @@ function hookSearch() {
   }
 
   search.select = function(result) {
-    window.location.href = result.firstChild.firstChild.href;
+    var href = result.firstChild.firstChild.href;
+    var query = this.input.value;
+    if (query) {
+      var url = new URL(href, window.location.origin);
+      url.searchParams.set('q', query);
+      url.searchParams.set('nav', '0');
+      href = url.toString();
+    }
+    window.location.href = href;
   }
 
   search.scrollIntoView = search.scrollInWindow;
+
+  // Check for ?q= URL parameter and trigger search automatically
+  if (typeof URLSearchParams !== 'undefined') {
+    var urlParams = new URLSearchParams(window.location.search);
+    var queryParam = urlParams.get('q');
+    if (queryParam) {
+      var navParam = urlParams.get('nav');
+      var autoSelect = navParam !== '0';
+      input.value = queryParam;
+      search.search(queryParam, autoSelect);
+    }
+  }
 };
 
 function hookFocus() {

data/lib/rdoc/generator/template/darkfish/js/search.js

@@ -34,6 +34,8 @@ Search.prototype = Object.assign({}, Navigation, new function() {
   }
 
   this.search = function(value, selectFirstMatch) {
+    this.selectFirstMatch = selectFirstMatch;
+
     value = value.trim().toLowerCase();
     if (value) {
       this.setNavigationActive(true);
@@ -76,7 +78,15 @@ Search.prototype = Object.assign({}, Navigation, new function() {
     //TODO: ECMAScript
     //if (jQuery.browser.msie) this.$element[0].className += '';
 
-    if (isLast) this.result.setAttribute('aria-busy', 'false');
+    if (this.selectFirstMatch && this.current) {
+      this.selectFirstMatch = false;
+      this.select(this.current);
+    }
+
+    if (isLast) {
+      this.selectFirstMatch = false;
+      this.result.setAttribute('aria-busy', 'false');
+    }
   }
 
   this.move = function(isDown) {

data/lib/rdoc/generator/template/json_index/js/searcher.js

@@ -58,7 +58,12 @@ Searcher.prototype = new function() {
 
   function buildRegexps(queries) {
     return queries.map(function(query) {
-      return new RegExp(query.replace(/(.)/g, '([$1])([^$1]*?)'), 'i');
+      var pattern = [];
+      for (var i = 0; i < query.length; i++) {
+        var char = RegExp.escape(query[i]);
+        pattern.push('([' + char + '])([^' + char + ']*?)');
+      }
+      return new RegExp(pattern.join(''), 'i');
     });
   }
 

data/lib/rdoc/markdown.kpeg

@@ -496,6 +496,57 @@
       "<s>#{text}</s>"
     end
   end
+
+  ##
+  # Wraps `text` in code markup for rdoc inline formatting
+
+  def code text
+    # trim even spaces
+    text = $2 while /\A( +|\t+)(.*)\1\z/ =~ text
+    # escape unescaped backslash at the end
+    backslash_at_end = "\\" if /(?<!\\)(?:\\\\)*\\\z/.match?(text)
+    "<code>#{text}#{backslash_at_end}</code>"
+  end
+
+  ##
+  # Parses inline markdown in table cells
+
+  def parse_table_cells(table)
+    # Parse header cells
+    table.header = table.header.map { |cell| parse_cell_inline(cell) }
+
+    # Parse body cells
+    table.body = table.body.map do |row|
+      row.map { |cell| parse_cell_inline(cell) }
+    end
+
+    table
+  end
+
+  ##
+  # Parses inline markdown in a single table cell
+
+  def parse_cell_inline(text)
+    return text if text.nil? || text.empty?
+
+    # Create a new parser instance for the cell
+    cell_parser = RDoc::Markdown.new(@extensions, @debug)
+
+    # Parse the cell content
+    doc = cell_parser.parse(text)
+
+    # Extract the parsed content
+    if doc && doc.parts && !doc.parts.empty?
+      para = doc.parts.first
+      if para.is_a?(RDoc::Markup::Paragraph)
+        para.parts.join
+      else
+        text
+      end
+    else
+      text
+    end
+  end
 }
 
 root = Doc
@@ -1064,32 +1115,32 @@ Ticks3 = "```" !"`"
 Ticks4 = "````" !"`"
 Ticks5 = "`````" !"`"
 
-Code = ( Ticks1 @Sp < (
+Code = ( Ticks1 < (
            ( !"`" Nonspacechar )+ | !Ticks1 /`+/ |
-           !( @Sp Ticks1 ) ( @Spacechar | @Newline !@BlankLine )
-         )+ > @Sp Ticks1 |
-         Ticks2 @Sp < (
+           !Ticks1 ( @Spacechar | @Newline !@BlankLine )
+         )+ > Ticks1 |
+         Ticks2 < (
            ( !"`" Nonspacechar )+ |
            !Ticks2 /`+/ |
-           !( @Sp Ticks2 ) ( @Spacechar | @Newline !@BlankLine )
-         )+ > @Sp Ticks2 |
-         Ticks3 @Sp < (
+           !Ticks2 ( @Spacechar | @Newline !@BlankLine )
+         )+ > Ticks2 |
+         Ticks3 < (
            ( !"`" Nonspacechar )+ |
            !Ticks3 /`+/ |
-           !( @Sp Ticks3 ) ( @Spacechar | @Newline !@BlankLine )
-         )+ > @Sp Ticks3 |
-         Ticks4 @Sp < (
+           !Ticks3 ( @Spacechar | @Newline !@BlankLine )
+         )+ > Ticks3 |
+         Ticks4 < (
            ( !"`" Nonspacechar )+ |
            !Ticks4 /`+/ |
-           !( @Sp Ticks4 ) ( @Spacechar | @Newline !@BlankLine )
-         )+ > @Sp Ticks4 |
-         Ticks5 @Sp < (
+           !Ticks4 ( @Spacechar | @Newline !@BlankLine )
+         )+ > Ticks4 |
+         Ticks5 < (
            ( !"`" Nonspacechar )+ |
            !Ticks5 /`+/ |
-           !( @Sp Ticks5 ) ( @Spacechar | @Newline !@BlankLine )
-         )+ > @Sp Ticks5
+           !Ticks5 ( @Spacechar | @Newline !@BlankLine )
+         )+ > Ticks5
        )
-       { "<code>#{text}</code>" }
+       { code text }
 
 RawHtml = < (HtmlComment | HtmlBlockScript | HtmlTag) >
           { if html? then text else '' end }
@@ -1201,7 +1252,10 @@ CodeFence = &{ github? }
 
 Table = &{ github? }
         TableHead:header TableLine:line TableRow+:body
-        { table = RDoc::Markup::Table.new(header, line, body) }
+        {
+          table = RDoc::Markup::Table.new(header, line, body)
+          parse_table_cells(table)
+        }
 
 TableHead = TableItem2+:items "|"? @Newline
             { items }
@@ -1210,7 +1264,7 @@ TableRow = ( ( TableItem:item1 TableItem2*:items { [item1, *items] } ):row | Tab
 	   { row }
 TableItem2 = "|" TableItem
 TableItem = < /(?:\\.|[^|\n])+/ >
-	    { text.strip.gsub(/\\(.)/, '\1')  }
+	    { text.strip.gsub(/\\([|])/, '\1')  }
 
 TableLine = ( ( TableAlign:align1 TableAlign2*:aligns {[align1, *aligns] } ):line | TableAlign2+:line ) "|"? @Newline
 	    { line }