rdoc 6.17.0 → 7.0.0

data/lib/rdoc/generator/template/aliki/js/search_ranker.js

@@ -0,0 +1,239 @@
+/**
+ * Aliki Search Implementation
+ *
+ * Search algorithm with the following priorities:
+ * 1. Exact full_name match always wins (for namespace/method queries)
+ * 2. Exact name match gets high priority
+ * 3. Match types:
+ *    - Namespace queries (::) and method queries (# or .) match against full_name
+ *    - Regular queries match against unqualified name
+ *    - Prefix (10000) > substring (5000) > fuzzy (1000)
+ * 4. First character determines type priority:
+ *    - Starts with lowercase: methods first
+ *    - Starts with uppercase: classes/modules/constants first
+ * 5. Within same type priority:
+ *    - Unqualified match > qualified match
+ *    - Shorter name > longer name
+ * 6. Class methods > instance methods
+ * 7. Result limit: 30
+ * 8. Minimum query length: 1 character
+ */
+
+var MAX_RESULTS = 30;
+var MIN_QUERY_LENGTH = 1;
+
+/*
+ * Scoring constants - organized in tiers where each tier dominates lower tiers.
+ * This ensures match type always beats type priority, etc.
+ *
+ * Tier 0: Exact matches (immediate return)
+ * Tier 1: Match type (prefix > substring > fuzzy)
+ * Tier 2: Exact name bonus
+ * Tier 3: Type priority (method vs class based on query case)
+ * Tier 4: Minor bonuses (top-level, class method, name length)
+ */
+var SCORE_EXACT_FULL_NAME = 1000000;  // Tier 0: Query exactly matches full_name
+var SCORE_MATCH_PREFIX    = 10000;    // Tier 1: Query is prefix of name
+var SCORE_MATCH_SUBSTRING = 5000;     // Tier 1: Query is substring of name
+var SCORE_MATCH_FUZZY     = 1000;     // Tier 1: Query chars appear in order
+var SCORE_EXACT_NAME      = 500;      // Tier 2: Name exactly equals query
+var SCORE_TYPE_PRIORITY   = 100;      // Tier 3: Preferred type (method/class)
+var SCORE_TOP_LEVEL       = 50;       // Tier 4: Top-level over namespaced
+var SCORE_CLASS_METHOD    = 10;       // Tier 4: Class method over instance method
+
+/**
+ * Check if all characters in query appear in order in target
+ * e.g., "addalias" fuzzy matches "add_foo_alias"
+ */
+function fuzzyMatch(target, query) {
+  var ti = 0;
+  for (var qi = 0; qi < query.length; qi++) {
+    ti = target.indexOf(query[qi], ti);
+    if (ti === -1) return false;
+    ti++;
+  }
+  return true;
+}
+
+/**
+ * Parse and normalize a search query
+ * @param {string} query - The raw search query
+ * @returns {Object} Parsed query with normalized form and flags
+ */
+function parseQuery(query) {
+  // Lowercase for case-insensitive matching (so "hash" finds both Hash class and #hash methods)
+  var normalized = query.toLowerCase();
+  var isNamespaceQuery = query.includes('::');
+  var isMethodQuery = query.includes('#') || query.includes('.');
+
+  // Normalize . to :: (RDoc uses :: for class methods in full_name)
+  if (query.includes('.')) {
+    normalized = normalized.replace(/\./g, '::');
+  }
+
+  return {
+    original: query,
+    normalized: normalized,
+    isNamespaceQuery: isNamespaceQuery,
+    isMethodQuery: isMethodQuery,
+    // Namespace and method queries match against full_name instead of name
+    matchesFullName: isNamespaceQuery || isMethodQuery,
+    // If query starts with lowercase, prioritize methods; otherwise prioritize classes/modules/constants
+    prioritizeMethod: !/^[A-Z]/.test(query)
+  };
+}
+
+/**
+ * Main search function
+ * @param {string} query - The search query
+ * @param {Array} index - The search index to search in
+ * @returns {Array} Array of matching entries, sorted by relevance
+ */
+function search(query, index) {
+  if (!query || query.length < MIN_QUERY_LENGTH) {
+    return [];
+  }
+
+  var q = parseQuery(query);
+  var results = [];
+
+  for (var i = 0; i < index.length; i++) {
+    var entry = index[i];
+    var score = computeScore(entry, q);
+
+    if (score !== null) {
+      results.push({ entry: entry, score: score });
+    }
+  }
+
+  results.sort(function(a, b) {
+    return b.score - a.score;
+  });
+
+  return results.slice(0, MAX_RESULTS).map(function(r) {
+    return r.entry;
+  });
+}
+
+/**
+ * Compute the relevance score for an entry
+ * @param {Object} entry - The search index entry
+ * @param {Object} q - Parsed query from parseQuery()
+ * @returns {number|null} Score or null if no match
+ */
+function computeScore(entry, q) {
+  var name = entry.name;
+  var fullName = entry.full_name;
+  var type = entry.type;
+
+  var nameLower = name.toLowerCase();
+  var fullNameLower = fullName.toLowerCase();
+
+  // Exact full_name match (e.g., "Array#filter" matches Array#filter)
+  if (q.matchesFullName && fullNameLower === q.normalized) {
+    return SCORE_EXACT_FULL_NAME;
+  }
+
+  var matchScore = 0;
+  var target = q.matchesFullName ? fullNameLower : nameLower;
+
+  if (target.startsWith(q.normalized)) {
+    matchScore = SCORE_MATCH_PREFIX;     // Prefix (e.g., "Arr" matches "Array")
+  } else if (target.includes(q.normalized)) {
+    matchScore = SCORE_MATCH_SUBSTRING;  // Substring (e.g., "ray" matches "Array")
+  } else if (fuzzyMatch(target, q.normalized)) {
+    matchScore = SCORE_MATCH_FUZZY;      // Fuzzy (e.g., "addalias" matches "add_foo_alias")
+  } else {
+    return null;
+  }
+
+  var score = matchScore;
+  var isMethod = (type === 'instance_method' || type === 'class_method');
+
+  if (q.prioritizeMethod ? isMethod : !isMethod) {
+    score += SCORE_TYPE_PRIORITY;
+  }
+
+  if (type === 'class_method') score += SCORE_CLASS_METHOD;
+  if (name === fullName) score += SCORE_TOP_LEVEL;  // Top-level (Hash) > namespaced (Foo::Hash)
+  if (nameLower === q.normalized) score += SCORE_EXACT_NAME;  // Exact name match
+  score -= name.length;
+
+  return score;
+}
+
+/**
+ * SearchRanker class for compatibility with the Search UI
+ * Provides ready() and find() interface
+ */
+function SearchRanker(index) {
+  this.index = index;
+  this.handlers = [];
+}
+
+SearchRanker.prototype.ready = function(fn) {
+  this.handlers.push(fn);
+};
+
+SearchRanker.prototype.find = function(query) {
+  var q = parseQuery(query);
+  var rawResults = search(query, this.index);
+  var results = rawResults.map(function(entry) {
+    return formatResult(entry, q);
+  });
+
+  var _this = this;
+  this.handlers.forEach(function(fn) {
+    fn.call(_this, results, true);
+  });
+};
+
+/**
+ * Format a search result entry for display
+ */
+function formatResult(entry, q) {
+  var result = {
+    title: highlightMatch(entry.full_name, q),
+    path: entry.path,
+    type: entry.type
+  };
+
+  if (entry.snippet) {
+    result.snippet = entry.snippet;
+  }
+
+  return result;
+}
+
+/**
+ * Add highlight markers (\u0001 and \u0002) to matching portions of text
+ * @param {string} text - The text to highlight
+ * @param {Object} q - Parsed query from parseQuery()
+ */
+function highlightMatch(text, q) {
+  if (!text || !q) return text;
+
+  var textLower = text.toLowerCase();
+  var query = q.normalized;
+
+  // Try contiguous match first (prefix or substring)
+  var matchIndex = textLower.indexOf(query);
+  if (matchIndex !== -1) {
+    return text.substring(0, matchIndex) +
+      '\u0001' + text.substring(matchIndex, matchIndex + query.length) + '\u0002' +
+      text.substring(matchIndex + query.length);
+  }
+
+  // Fall back to fuzzy highlight (highlight each matched character)
+  var result = '';
+  var ti = 0;
+  for (var qi = 0; qi < query.length; qi++) {
+    var charIndex = textLower.indexOf(query[qi], ti);
+    if (charIndex === -1) return text;
+    result += text.substring(ti, charIndex);
+    result += '\u0001' + text[charIndex] + '\u0002';
+    ti = charIndex + 1;
+  }
+  result += text.substring(ti);
+  return result;
+}

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

@@ -163,15 +163,13 @@
               <summary>Source</summary>
             </details>
           </div>
+          <div class="method-source-code" id="<%= method.html_name %>-source">
+            <pre><%= method.markup_code %></pre>
+          </div>
         <%- end %>
 
         <%- unless method.skip_description? then %>
         <div class="method-description">
-          <%- if method.token_stream then %>
-          <div class="method-source-code" id="<%= method.html_name %>-source">
-            <pre><%= method.markup_code %></pre>
-          </div>
-          <%- end %>
           <%- if method.mixin_from then %>
             <div class="mixin-from">
               <%= method.singleton ? "Extended" : "Included" %> from <a href="<%= klass.aref_to(method.mixin_from.path) %>"><%= method.mixin_from.full_name %></a>

data/lib/rdoc/options.rb

@@ -411,7 +411,7 @@ class RDoc::Options
     @files = nil
     @force_output = false
     @force_update = true
-    @generator_name = "darkfish"
+    @generator_name = "aliki"
     @generators = RDoc::RDoc::GENERATORS
     @generator_options = []
     @hyperlink_all = false

data/lib/rdoc/rubygems_hook.rb

@@ -118,7 +118,7 @@ class RDoc::RubyGemsHook
   end
 
   ##
-  # Generates documentation using the named +generator+ ("darkfish" or "ri")
+  # Generates documentation using the named +generator+ ("aliki" or "ri")
   # and following the given +options+.
   #
   # Documentation will be generated into +destination+
@@ -190,7 +190,7 @@ class RDoc::RubyGemsHook
 
     Dir.chdir @spec.full_gem_path do
       # RDoc::Options#finish must be called before parse_files.
-      # RDoc::Options#finish is also called after ri/darkfish generator setup.
+      # RDoc::Options#finish is also called after ri/aliki generator setup.
       # We need to dup the options to avoid modifying it after finish is called.
       parse_options = options.dup
       parse_options.finish
@@ -202,7 +202,7 @@ class RDoc::RubyGemsHook
     document 'ri',       options, @ri_dir if
       @generate_ri   and (@force or not File.exist? @ri_dir)
 
-    document 'darkfish', options, @rdoc_dir if
+    document 'aliki', options, @rdoc_dir if
       @generate_rdoc and (@force or not File.exist? @rdoc_dir)
   end
 

data/lib/rdoc/version.rb

@@ -5,6 +5,6 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '6.17.0'
+  VERSION = '7.0.0'
 
 end

data/rdoc.gemspec

@@ -38,7 +38,7 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
   # for ruby core repository. It was generated by
   # `git ls-files -z`.split("\x0").each {|f| puts "    #{f.dump}," unless f.start_with?(*%W[test/ spec/ features/ .]) }
   non_lib_files = [
-    "CONTRIBUTING.rdoc",
+    "CONTRIBUTING.md",
     "CVE-2013-0256.rdoc",
     "ExampleMarkdown.md",
     "ExampleRDoc.rdoc",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc
 version: !ruby/object:Gem::Version
-  version: 6.17.0
+  version: 7.0.0
 platform: ruby
 authors:
 - Eric Hodel
@@ -13,7 +13,7 @@ authors:
 - ITOYANAGI Sakura
 bindir: exe
 cert_chain: []
-date: 2025-12-07 00:00:00.000000000 Z
+date: 2025-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: psych
@@ -73,7 +73,7 @@ executables:
 - ri
 extensions: []
 extra_rdoc_files:
-- CONTRIBUTING.rdoc
+- CONTRIBUTING.md
 - CVE-2013-0256.rdoc
 - ExampleMarkdown.md
 - ExampleRDoc.rdoc
@@ -84,7 +84,7 @@ extra_rdoc_files:
 - RI.md
 - TODO.rdoc
 files:
-- CONTRIBUTING.rdoc
+- CONTRIBUTING.md
 - CVE-2013-0256.rdoc
 - ExampleMarkdown.md
 - ExampleRDoc.rdoc
@@ -153,7 +153,9 @@ files:
 - lib/rdoc/generator/template/aliki/index.rhtml
 - lib/rdoc/generator/template/aliki/js/aliki.js
 - lib/rdoc/generator/template/aliki/js/c_highlighter.js
-- lib/rdoc/generator/template/aliki/js/search.js
+- lib/rdoc/generator/template/aliki/js/search_controller.js
+- lib/rdoc/generator/template/aliki/js/search_navigation.js
+- lib/rdoc/generator/template/aliki/js/search_ranker.js
 - lib/rdoc/generator/template/aliki/js/theme-toggle.js
 - lib/rdoc/generator/template/aliki/page.rhtml
 - lib/rdoc/generator/template/aliki/servlet_not_found.rhtml
@@ -322,7 +324,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '2.2'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: RDoc produces HTML and command-line documentation for Ruby projects
 test_files: []

data/CONTRIBUTING.rdoc

@@ -1,219 +0,0 @@
-= Developer Introduction
-
-So you want to write a generator, fix a bug, or otherwise work with RDoc.  This
-document provides an overview of how RDoc works from parsing options to
-generating output.  Most of the documentation can be found in the specific
-classes for each feature.
-
-== Bugs
-
-If you think you found a bug, file a ticket on the {issues
-tracker}[https://github.com/ruby/rdoc/issues] on github.
-
-If your bug involves an error RDoc produced please include a sample file that
-illustrates the problem or link to the repository or gem that is associated
-with the bug.
-
-Please include steps to reproduce the issue.  Here are some examples of good
-issues:
-
-* https://github.com/ruby/rdoc/issues/55
-* https://github.com/ruby/rdoc/issues/61
-
-== Developer Quick Start
-
-RDoc uses bundler for development.  To get ready to work on RDoc run:
-
-  $ gem install bundler
-  [...]
-  $ bundle install
-  [...]
-  $ rake
-  [...]
-
-This will install all the necessary dependencies for development with rake,
-generate documentation and run the tests for the first time.
-
-If the tests don't pass on the first run check the {GitHub Actions page}[https://github.com/ruby/rdoc/actions] to see if there are any known failures
-(there shouldn't be).
-
-You can now use `rake` and `autotest` to run the tests.
-
-Note: the `rake` command must be used first before running any tests, because
-it's used to generate various parsers implemented in RDoc. Also `rake clean` is
-helpful to delete these generated files.
-
-== Glossary
-
-Here are definitions for some common terms in the RDoc documentation.  The
-list also briefly describes how the components of RDoc interact.
-
-parser::
-  Parses files and creates a documentation tree from the contents.
-
-documentation tree::
-  The documentation tree represents files, classes, modules, methods,
-  constants, includes, comments and other ruby syntax features as a tree.
-  RDoc walks this tree with a generator to create documentation.
-
-generator::
-  Walks the documentation tree and generates output.
-
-  RDoc ships with two generators, the Darkfish generator creates HTML and the
-  RI generator creates an RI data store.
-
-markup parser::
-  Parses comments from a file into a generic markup tree.
-
-  The markup parsers allow RDoc to handle RDoc, TomDoc, rd and Markdown format
-  documentation with common formatters.
-
-markup tree::
-  Each parsed comment has a markup tree that represents common markup items
-  such as headings, paragraphs, lists or verbatim text sections for example
-  code or output.
-
-  A generator uses a formatters to walks the tree to create output.  Some
-  generators use multiple formatters on a markup tree to produce the output.
-
-formatter::
-  Converts a parsed markup tree into some form other form of markup.
-
-  Formatters can either produce a one-to-one conversion, such as ToHtml, or
-  extract part of the parsed result, such as ToHtmlSnippet which outputs the
-  first 100 characters as HTML.
-
-== Plugins
-
-When 'rdoc/rdoc' is loaded RDoc looks for 'rdoc/discover' files in your
-installed gems.  This can be used to load parsers, alternate generators, or
-additional preprocessor directives.  An rdoc plugin layout should look
-something like this:
-
-  lib/rdoc/discover.rb
-  lib/my/rdoc/plugin.rb
-  # etc.
-
-In your rdoc/discover.rb file you will want to wrap the loading of your plugin
-in an RDoc version check like this:
-
-  begin
-    gem 'rdoc', '~> 3'
-    require 'my/rdoc/plugin'
-  rescue Gem::LoadError
-  end
-
-=== Plugin Types
-
-In RDoc you can change the following behaviors:
-
-* Add a parser for a new file format
-* Add a new output generator
-* Add a new markup directive
-* Add a new type of documentation markup
-* Add a new type of formatter
-
-All of these are described below
-
-== Option Parsing
-
-Option parsing is handled by RDoc::Options.  When you're writing a generator
-you can provide the user with extra options by providing a class method
-+setup_options+.  The option parser will call this after your generator is
-loaded.  See RDoc::Generator for details.
-
-== File Parsing
-
-After options are parsed, RDoc parses files from the files and directories in
-ARGV.  RDoc compares the filename against what each parser claims it can parse
-via RDoc::Parser#parse_files_matching.  For example, RDoc::Parser::C can parse
-C files, C headers, C++ files, C++ headers and yacc grammars.
-
-Once a matching parser class is found it is instantiated and +scan+ is called.
-The parser needs to extract documentation from the file and add it to the RDoc
-document tree.  Usually this involves starting at the root and adding a class
-or a module (RDoc::TopLevel#add_class and RDoc::TopLevel#add_module) and
-proceeding to add classes, modules and methods to each nested item.
-
-When the parsers are finished the document tree is cleaned up to remove
-dangling references to aliases and includes that were not found (and may exist
-in a separate library) through RDoc::ClassModule#complete.
-
-To write your own parser for a new file format see RDoc::Parser.
-
-=== Documentation Tree
-
-The parsers build a documentation tree that is composed of RDoc::CodeObject and
-its subclasses.  There are various methods to walk the tree to extract
-information, see RDoc::Context and its subclasses.
-
-Within a class or module, attributes, methods and constants are divided into
-sections.  The section represents a functional grouping of parts of the class.
-TomDoc uses the sections "Public", "Internal" and "Deprecated".  The sections
-can be enumerated using RDoc::Context#each_section.
-
-== Output Generation
-
-An RDoc generator turns the documentation tree into some other kind of output.
-RDoc comes with an HTML generator (RDoc::Generator::Darkfish) and an RI
-database generator (RDoc::Generator::RI).  The output a generator creates does
-not have to be human-readable.
-
-To create your own generator see RDoc::Generator.
-
-=== Comments
-
-In RDoc 3.10 and newer the comment on an RDoc::CodeObject is now an
-RDoc::Comment object instead of a String.  This is to support various
-documentation markup formats like rdoc, TomDoc and rd.  The comments are
-normalized to remove comment markers and remove indentation then parsed lazily
-via RDoc::Comment#document to create a generic markup tree that can be
-processed by a formatter.
-
-To add your own markup format see RDoc::Markup@Other+directives
-
-==== Formatters
-
-To transform a comment into some form of output an RDoc::Markup::Formatter
-subclass is used like RDoc::Markup::ToHtml.  A formatter is a visitor that
-walks a parsed comment tree (an RDoc::Markup::Document) of any format.  To help
-write a formatter RDoc::Markup::FormatterTestCase exists for generic parsers,
-and RDoc::Markup::TextFormatterTestCase which contains extra test cases for
-text-type output (like +ri+ output).
-
-RDoc ships with formatters that will turn a comment into HTML, rdoc-markup-like
-text, ANSI or terminal backspace highlighted text, HTML, cross-referenced HTML,
-an HTML snippet free of most markup, an HTML label for use in id attributes, a
-table-of-contents page, and text with only code blocks.
-
-The output of the formatter does not need to be text or text-like.
-RDoc::Markup::ToLabel creates an HTML-safe label for use in an HTML id
-attribute.  A formatter could count the number of words and the average word
-length for a comment, for example.
-
-==== Directives
-
-For comments in markup you can add new directives (:nodoc: is a directive).
-Directives may replace text or store it off for later use.
-
-See RDoc::Markup::PreProcess::register for details.
-
-=== JSONIndex
-
-RDoc contains a special generator, RDoc::Generator::JSONIndex, which creates a
-JSON-based search index and includes a search engine for use with HTML output.
-This generator can be used to add searching to any HTML output and is designed
-to be called from inside an HTML generator.
-
-== Markup
-
-Additional documentation markup formats can be added to RDoc.  A markup
-parsing class must respond to \::parse and accept a String argument containing
-the markup format.  An RDoc::Document containing documentation items
-(RDoc::Markup::Heading, RDoc::Markup::Paragraph, RDoc::Markup::Verbatim, etc.)
-must be returned.
-
-To register the parser with rdoc, add the markup type's name and class to the
-RDoc::Text::MARKUP_FORMAT hash like:
-
-  RDoc::Text::MARKUP_FORMAT['rdoc'] = RDoc::Markup