diff --git a/CONTRIBUTING.rdoc b/CONTRIBUTING.rdoc index d76eb6b0ad..0147b1db93 100644 --- a/CONTRIBUTING.rdoc +++ b/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 rake clean 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,7 +105,7 @@ 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 @@ -113,11 +113,11 @@ In RDoc you can change the following behaviors: * 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,14 +193,14 @@ 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. @@ -208,8 +208,8 @@ 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.