rdoc 3.1 → 6.3.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 120ff1fdb58f0543a2a49d1e4fffc2ebaf3f1bcd9f3cd2006f4130b6a4caa330
+  data.tar.gz: 7c8dabbb3b1256e4bca4b2a14dfb216d43f9bb3acb26d5277b7acbbf6212f5eb
+SHA512:
+  metadata.gz: 38fa507c6bf06b2697642b7a133fcb42ed256aa7b788c7ca6eaba7545d92e071325e2b175020716fca082864efff9e2702aa05f5e5b758e06aa3c3947c972449
+  data.tar.gz: 655ceb71a41d8e17202c9ecab7dd41af87f30fd16a5be757778f3671563f8779f82982b223b68610c9a7e37899e5311a9614fbbb7df8f80c9533358a4db480cf

data/CONTRIBUTING.rdoc

@@ -0,0 +1,220 @@
+= 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 {Travis CI page for
+RDoc}[https://travis-ci.org/ruby/rdoc] 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
+its 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

data/CVE-2013-0256.rdoc

@@ -0,0 +1,49 @@
+= RDoc 2.3.0 through 3.12 XSS Exploit
+
+RDoc documentation generated by rdoc 2.3.0 through rdoc 3.12 and prereleases up
+to rdoc 4.0.0.preview2.1 are vulnerable to an XSS exploit.  This exploit may
+lead to cookie disclosure to third parties.
+
+The exploit exists in darkfish.js which is copied from the RDoc install
+location to the generated documentation.
+
+RDoc is a static documentation generation tool.  Patching the library itself
+is insufficient to correct this exploit.  Those hosting rdoc documentation will
+need to apply the following patch.  If applied while ignoring whitespace, this
+patch will correct all affected versions:
+
+  diff --git darkfish.js darkfish.js
+  index 4be722f..f26fd45 100644
+  --- darkfish.js
+  +++ darkfish.js
+  @@ -109,13 +109,15 @@ function hookSearch() {
+   function highlightTarget( anchor ) {
+     console.debug( "Highlighting target '%s'.", anchor );
+   
+  -  $("a[name=" + anchor + "]").each( function() {
+  -    if ( !$(this).parent().parent().hasClass('target-section') ) {
+  -      console.debug( "Wrapping the target-section" );
+  -      $('div.method-detail').unwrap( 'div.target-section' );
+  -      $(this).parent().wrap( '<div class="target-section"></div>' );
+  -    } else {
+  -      console.debug( "Already wrapped." );
+  +  $("a[name]").each( function() {
+  +    if ( $(this).attr("name") == anchor ) {
+  +      if ( !$(this).parent().parent().hasClass('target-section') ) {
+  +        console.debug( "Wrapping the target-section" );
+  +        $('div.method-detail').unwrap( 'div.target-section' );
+  +        $(this).parent().wrap( '<div class="target-section"></div>' );
+  +      } else {
+  +        console.debug( "Already wrapped." );
+  +      }
+       }
+     });
+   };
+
+RDoc 3.9.5, 3.12.1 and RDoc 4.0.0.rc.2 and newer are not vulnerable to this
+exploit.
+
+This exploit was discovered by Evgeny Ermakov <corwmh@gmail.com>.
+
+This vulnerability has been assigned the CVE identifier CVE-2013-0256.
+

data/ExampleMarkdown.md

@@ -0,0 +1,37 @@
+This document contains example output to show RDoc styling.  This file was
+created from a Markdown file.
+
+For the following styles, see ExampleRDoc.rdoc for style examples:
+
+* Headings
+* Paragraphs
+* Code blocks (verbatim sections)
+* Definition lists
+* Ordered lists
+* Unordered lists
+
+These items all use the same styles as RDoc format files.
+
+## Footnotes
+
+Footnotes are rendered at the bottom of the documentation section[^1].  For
+pages this will be at the bottom of the page.  For method documentation this
+will be at the end of the current method.
+
+[^1]: Here is the footnote content.  As you can see it is at the bottom of the
+page.
+
+## Blockquotes
+
+Here is how a blockquote looks.
+
+> We finished our first sensor sweep of the neutral zone. Now, how the hell do
+> we defeat an enemy that knows us better than we know ourselves? and attack
+> the Romulans.
+>
+> > Sorry, Data. I guess it's better to be lucky than good. The unexpected is
+> > our normal routine. Could someone survive inside a transporter buffer for
+> > 75 years?
+
+This text is from [Riker Ipsum](http://rikeripsum.com)
+

data/ExampleRDoc.rdoc

@@ -0,0 +1,208 @@
+This document contains example output to show RDoc styling.  This file was
+created from a RDoc Markup file.
+
+== Headings
+
+You should not use headings beyond level 3, it is a sign of poor organization
+of your code or documentation.  It also becomes difficult for the user to
+figure out what you are attempting to explain to them as they have to track
+the multiple layers of nesting.
+
+= Heading level 1
+
+Above is a level one heading.
+
+These paragraphs are filler that exist so you can see how the heading
+interacts with paragraphs before and after the heading.  As you can see each
+different heading has a different amount of margin above and below.
+
+This should be sufficient to give you a proper picture of how it will appear in
+your documentation.
+
+== Heading level 2
+
+Above is a level two heading.
+
+These paragraphs are filler that exist so you can see how the heading
+interacts with paragraphs before and after the heading.  As you can see each
+different heading has a different amount of margin above and below.
+
+This should be sufficient to give you a proper picture of how it will appear in
+your documentation.
+
+=== Heading level 3
+
+Above is a level three heading.
+
+These paragraphs are filler that exist so you can see how the heading
+interacts with paragraphs before and after the heading.  As you can see each
+different heading has a different amount of margin above and below.
+
+This should be sufficient to give you a proper picture of how it will appear in
+your documentation.
+
+==== Heading level 4
+
+Above is a level four heading.
+
+These paragraphs are filler that exist so you can see how the heading
+interacts with paragraphs before and after the heading.  As you can see each
+different heading has a different amount of margin above and below.
+
+This should be sufficient to give you a proper picture of how it will appear in
+your documentation.
+
+===== Heading level 5
+
+Above is a level five heading.
+
+These paragraphs are filler that exist so you can see how the heading
+interacts with paragraphs before and after the heading.  As you can see each
+different heading has a different amount of margin above and below.
+
+This should be sufficient to give you a proper picture of how it will appear in
+your documentation.
+
+====== Heading level 6
+
+Above is a level six heading.
+
+These paragraphs are filler that exist so you can see how the heading
+interacts with paragraphs before and after the heading.  As you can see each
+different heading has a different amount of margin above and below.
+
+This should be sufficient to give you a proper picture of how it will appear in
+your documentation.
+
+== Paragraphs
+
+This is how a paragraph looks.  Since it is difficult to generate good content
+for paragraphs I have chosen to use {Riker Ipsum}[http://rikeripsum.com] for
+nonsense filler content.  In the previous sentence you can see how a link is
+formatted.
+
+Here is an example of *bold* and _emphasis_ styling.  Try not to combine the
+two or use them too often.  Here is an example of <code>inline verbatim
+text</code>.  That should be enough of a taste of inline markup in paragraphs.
+The Riker Ipsum filler follows:
+
+Shields up! Rrrrred alert! Well, I'll say this for him - he's sure of himself.
+and attack the Romulans. Worf, It's better than music. It's jazz. This should
+be interesting. When has justice ever been as simple as a rule book? Flair is
+what marks the difference between artistry and mere competence.
+
+Sorry, Data. I think you've let your personal feelings cloud your judgement. We
+finished our first sensor sweep of the neutral zone. Yes, absolutely, I do
+indeed concur, wholeheartedly! Mr. Worf, you do remember how to fire phasers? A
+lot of things can change in twelve years, Admiral. Your shields were failing,
+sir.
+
+== Verbatim sections
+
+A verbatim section typically contains source code or example output.  This is
+how verbatim blocks of code looks:
+
+  def local responder
+    responder.ping do |value|
+      return value
+    end
+  end
+  
+  def ping uri
+    @uri = uri
+    @remote = DRb::DRbObject.new_with_uri @uri
+  
+    @remote.ping do |value|
+      return value
+    end
+  end
+
+This is a paragraph following the verbatim block so you can see how leading and trailing paragraphs interact with it.
+
+== Unordered lists
+
+Here is an unordered list.  As you can see it uses non-numeral markers for each list item:
+
+* This is the top-most item in the list.
+* This is a second item in the list.
+
+  Unlike the first item, this item has more than one paragraph so you can see
+  how they interact.
+* This is a third item in the list.  Like the item before it, this item has a
+  second paragraph.
+
+  Here is the second paragraph in the list item.
+* A final list item.
+
+== Ordered lists
+
+Here is an ordered list.  As you can see it uses numeral markers for each list
+item:
+
+1. This is the first item in the list.
+1. This is the second item in the list.
+
+   Unlike the first item, this item has more than one paragraph so you can see
+   how they interact.
+1. This is the third item in the list.  Like the item before it, this item has
+   a second paragraph.
+
+   Here is the second paragraph in the third list item.
+1. The fourth and final list item.
+
+== Definition lists
+
+=== "Note" list
+
+The "note" syntax can be used to create a definition list:
+
+  note::
+    description
+
+Here is such a definition list:
+
+cat::
+  A cat is a small mammal that is commonly kept as a pet.
+
+dog::
+  A dog is a mammal that is also kept as a pet.  A dog may range in size from
+  smaller than a cat to larger than a human.
+
+  Typically dogs are easier to train to respond to commands than cats.
+
+rabbit::
+  Rabbits are also mammals, but are infrequently kept as pets.  Most rabbits
+  are wild.
+
+=== "Label" list
+
+The "label" syntax can be used to create a definition list:
+
+  [label]
+    description
+
+Here is such a definition list:
+
+[cat]
+  A cat is a small mammal that is commonly kept as a pet.
+
+[dog]
+  A dog is a mammal that is also kept as a pet.  A dog may range in size from
+  smaller than a cat to larger than a human.
+
+  Typically dogs are easier to train to respond to commands than cats.
+
+[rabbit]
+  Rabbits are also mammals, but are infrequently kept as pets.  Most rabbits
+  are wild.
+
+== Rule
+
+A rule is a horizontal divider between two paragraphs.  Following this
+paragraph is a rule.
+
+---
+
+In historic versions of RDoc you could control the height of the rule in HTML
+output.  This is no longer true as HTML 5 does not support this.
+

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem "rake"
+  gem "racc", "> 1.4.10"
+  gem "kpeg"
+  gem "test-unit"
+  gem "minitest" # for test_rdoc_rubygems_hook.rb
+  gem "rubocop"
+end