Improve CONTRIBUTING.rdoc

CONTRIBUTING.rdoc

@@ -8,9 +8,9 @@ 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.
+tracker}[https://github.com/ruby/rdoc/issues] on GitHub.
 
-If your bug involves an error RDoc produced please include a sample file that
+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.
 
@@ -28,19 +28,19 @@ RDoc uses bundler for development.  To get ready to work on RDoc run:
   [...]
   $ bundle install
   [...]
-  $ rake
+  $ bundle exec rake
   [...]
 
-This will install all the necessary dependencies for development with 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).
+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.
+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
+Note: the +rake+ command must be used first before running any tests, because
+it's used to generate various parsers implemented in RDoc. Also <tt>rake clean</tt> is
 helpful to delete these generated files.
 
 == Glossary
@@ -85,7 +85,7 @@ formatter::
 
 == Plugins
 
-When 'rdoc/rdoc' is loaded RDoc looks for 'rdoc/discover' files in your
+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:
@@ -94,7 +94,7 @@ something like this:
   lib/my/rdoc/plugin.rb
   # etc.
 
-In your rdoc/discover.rb file you will want to wrap the loading of your plugin
+In your +rdoc/discover.rb+ file, you will want to wrap the loading of your plugin
 in an RDoc version check like this:
 
   begin
@@ -105,19 +105,19 @@ in an RDoc version check like this:
 
 === Plugin Types
 
-In RDoc you can change the following behaviors:
+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
+All of these are described below.
 
 == Option Parsing
 
-Option parsing is handled by RDoc::Options.  When you're writing a generator
+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.
@@ -126,20 +126,20 @@ loaded.  See RDoc::Generator for details.
 
 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
+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
+Once a matching parser class is found, it is instantiated and +scan+ is called.
+The parser needs to extract documentation from the file and adds 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
+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.
+To write your own parser for a new file format, see RDoc::Parser.
 
 === Documentation Tree
 
@@ -159,26 +159,26 @@ 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.
+To create your own generator, see RDoc::Generator.
 
 === Comments
 
-In RDoc 3.10 and newer the comment on an RDoc::CodeObject is now an
+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
+normalized to remove comment markers and indentation, and 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
+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
+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
@@ -193,23 +193,23 @@ length for a comment, for example.
 
 ==== Directives
 
-For comments in markup you can add new directives (:nodoc: is a directive).
+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
+=== JSON Index
 
-RDoc contains a special generator, RDoc::Generator::JSONIndex, which creates a
+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
+parsing class must respond to +::parse+ and accept a String argument containing
+the markup format.  An RDoc::Markup::Document containing documentation items
 (RDoc::Markup::Heading, RDoc::Markup::Paragraph, RDoc::Markup::Verbatim, etc.)
 must be returned.