CINXE.COM

<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>rdoc Documentation</title> <meta name="keywords" content="ruby,documentation,rdoc Documentation"> <meta name="description" content="rdoc Documentation: Description RDoc produces HTML and command-line documentation for Ruby projects. RDoc includes the +rdoc+ and +ri+ tools for generating and displayin"> <script type="text/javascript"> var rdoc_rel_prefix = "./"; var index_rel_prefix = "./"; </script> <script src="./js/navigation.js" defer></script> <script src="./js/search.js" defer></script> <script src="./js/search_index.js" defer></script> <script src="./js/searcher.js" defer></script> <script src="./js/darkfish.js" defer></script> <link href="./css/fonts.css" rel="stylesheet"> <link href="./css/rdoc.css" rel="stylesheet"> <body id="top" role="document" class="file"> <div id="navigation-toggle" role="button" tabindex="0" aria-label="Toggle sidebar" aria-expanded="true" aria-controls="navigation"> <span aria-hidden="true">☰</span> </div> <nav id="navigation" role="navigation"> <div id="project-navigation"> <div id="home-section" role="region" title="Quick navigation" class="nav-section"> <h2> <a href="./index.html" rel="home">Home</a> </h2> <div id="table-of-contents-navigation"> <a href="./table_of_contents.html#pages">Pages</a> <a href="./table_of_contents.html#classes">Classes</a> <a href="./table_of_contents.html#methods">Methods</a> </div> </div> <div id="search-section" role="search" class="project-section initially-hidden"> <form action="#" method="get" accept-charset="utf-8"> <div id="search-field-wrapper"> <input id="search-field" role="combobox" aria-label="Search" aria-autocomplete="list" aria-controls="search-results" type="text" name="search" placeholder="Search (/) for a class, method, ..." spellcheck="false" title="Type to search, Up and Down to navigate, Enter to load"> </div> <ul id="search-results" aria-label="Search Results" aria-busy="false" aria-expanded="false" aria-atomic="false" class="initially-hidden"></ul> </form> </div> </div> <div class="nav-section"> <h3>Table of Contents</h3> <ul class="link-list" role="directory"> <li> <details open> <summary> <a href="#label-RDoc+-+Ruby+Documentation+System">RDoc - Ruby Documentation System</a> </summary> <ul class="link-list" role="directory"> <li> <a href="#label-Description">Description</a> <li> <a href="#label-Generating+Documentation">Generating Documentation</a> <li> <a href="#label-Writing+Documentation">Writing Documentation</a> <li> <a href="#label-Theme+Options">Theme Options</a> <li> <a href="#label-Bugs">Bugs</a> <li> <a href="#label-License">License</a> <li> <a href="#label-Warranty">Warranty</a> </ul> </details> </li> </ul> </div> <div id="fileindex-section" class="nav-section"> <h3>Pages</h3> <ul class="link-list"> <li><a href="./CONTRIBUTING_rdoc.html">CONTRIBUTING</a> <li><a href="./CVE-2013-0256_rdoc.html">CVE-2013-0256</a> <li><a href="./ExampleMarkdown_md.html">ExampleMarkdown</a> <li><a href="./ExampleRDoc_rdoc.html">ExampleRDoc</a> <li><a href="./History_rdoc.html">History</a> <li><a href="./LEGAL_rdoc.html">LEGAL</a> <li><a href="./LICENSE_rdoc.html">LICENSE</a> <li><a href="./README_rdoc.html">README</a> <li><a href="./RI_md.html">RI</a> <li><a href="./TODO_rdoc.html">TODO</a> <li><a href="./lib/rdoc/markdown_kpeg.html">markdown.kpeg</a> </ul> </div> <div id="classindex-section" class="nav-section"> <h3>Class and Module Index</h3> <ul class="link-list"><li><details open><summary><code><a href="./RDoc.html">RDoc</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Alias.html">Alias</a></code></li><li><code><a href="./RDoc/AnonClass.html">AnonClass</a></code></li><li><code><a href="./RDoc/AnyMethod.html">AnyMethod</a></code></li><li><code><a href="./RDoc/Attr.html">Attr</a></code></li><li><code><a href="./RDoc/ClassModule.html">ClassModule</a></code></li><li><code><a href="./RDoc/CodeObject.html">CodeObject</a></code></li><li><code><a href="./RDoc/Comment.html">Comment</a></code></li><li><code><a href="./RDoc/Constant.html">Constant</a></code></li><li><details><summary><code><a href="./RDoc/Context.html">Context</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Context/Section.html">Section</a></code></li></ul></details></li><li><code><a href="./RDoc/CrossReference.html">CrossReference</a></code></li><li><code><a href="./RDoc/ERBIO.html">ERBIO</a></code></li><li><code><a href="./RDoc/ERBPartial.html">ERBPartial</a></code></li><li><code><a href="./RDoc/Encoding.html">Encoding</a></code></li><li><code><a href="./RDoc/Error.html">Error</a></code></li><li><code><a href="./RDoc/Extend.html">Extend</a></code></li><li><details><summary><code><a href="./RDoc/Generator.html">Generator</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Generator/Darkfish.html">Darkfish</a></code></li><li><code><a href="./RDoc/Generator/JsonIndex.html">JsonIndex</a></code></li><li><code><a href="./RDoc/Generator/Markup.html">Markup</a></code></li><li><details><summary><code><a href="./RDoc/Generator/POT.html">POT</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Generator/POT/MessageExtractor.html">MessageExtractor</a></code></li><li><code><a href="./RDoc/Generator/POT/PO.html">PO</a></code></li><li><code><a href="./RDoc/Generator/POT/POEntry.html">POEntry</a></code></li></ul></details></li><li><code><a href="./RDoc/Generator/RI.html">RI</a></code></li></ul></details></li><li><code><a href="./RDoc/GhostMethod.html">GhostMethod</a></code></li><li><details><summary><code><a href="./RDoc/I18n.html">I18n</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/I18n/Locale.html">Locale</a></code></li><li><code><a href="./RDoc/I18n/Text.html">Text</a></code></li></ul></details></li><li><code><a href="./RDoc/Include.html">Include</a></code></li><li><details><summary><code><a href="./RDoc/Markdown.html">Markdown</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Markdown/Literals.html">Literals</a></code></li></ul></details></li><li><details><summary><code><a href="./RDoc/Markup.html">Markup</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Markup/AttrChanger.html">AttrChanger</a></code></li><li><code><a href="./RDoc/Markup/AttrSpan.html">AttrSpan</a></code></li><li><code><a href="./RDoc/Markup/AttributeManager.html">AttributeManager</a></code></li><li><code><a href="./RDoc/Markup/Attributes.html">Attributes</a></code></li><li><code><a href="./RDoc/Markup/BlankLine.html">BlankLine</a></code></li><li><code><a href="./RDoc/Markup/BlockQuote.html">BlockQuote</a></code></li><li><code><a href="./RDoc/Markup/Document.html">Document</a></code></li><li><code><a href="./RDoc/Markup/Formatter.html">Formatter</a></code></li><li><code><a href="./RDoc/Markup/HardBreak.html">HardBreak</a></code></li><li><code><a href="./RDoc/Markup/Include.html">Include</a></code></li><li><code><a href="./RDoc/Markup/IndentedParagraph.html">IndentedParagraph</a></code></li><li><code><a href="./RDoc/Markup/List.html">List</a></code></li><li><code><a href="./RDoc/Markup/ListItem.html">ListItem</a></code></li><li><code><a href="./RDoc/Markup/Paragraph.html">Paragraph</a></code></li><li><details><summary><code><a href="./RDoc/Markup/Parser.html">Parser</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Markup/Parser/Error.html">Error</a></code></li><li><code><a href="./RDoc/Markup/Parser/MyStringScanner.html">MyStringScanner</a></code></li><li><code><a href="./RDoc/Markup/Parser/ParseError.html">ParseError</a></code></li></ul></details></li><li><code><a href="./RDoc/Markup/PreProcess.html">PreProcess</a></code></li><li><code><a href="./RDoc/Markup/Raw.html">Raw</a></code></li><li><code><a href="./RDoc/Markup/RegexpHandling.html">RegexpHandling</a></code></li><li><code><a href="./RDoc/Markup/Rule.html">Rule</a></code></li><li><code><a href="./RDoc/Markup/Table.html">Table</a></code></li><li><code><a href="./RDoc/Markup/ToAnsi.html">ToAnsi</a></code></li><li><code><a href="./RDoc/Markup/ToBs.html">ToBs</a></code></li><li><code><a href="./RDoc/Markup/ToHtml.html">ToHtml</a></code></li><li><code><a href="./RDoc/Markup/ToHtmlCrossref.html">ToHtmlCrossref</a></code></li><li><code><a href="./RDoc/Markup/ToHtmlSnippet.html">ToHtmlSnippet</a></code></li><li><code><a href="./RDoc/Markup/ToJoinedParagraph.html">ToJoinedParagraph</a></code></li><li><code><a href="./RDoc/Markup/ToLabel.html">ToLabel</a></code></li><li><code><a href="./RDoc/Markup/ToMarkdown.html">ToMarkdown</a></code></li><li><code><a href="./RDoc/Markup/ToRdoc.html">ToRdoc</a></code></li><li><code><a href="./RDoc/Markup/ToTableOfContents.html">ToTableOfContents</a></code></li><li><code><a href="./RDoc/Markup/ToTest.html">ToTest</a></code></li><li><code><a href="./RDoc/Markup/ToTtOnly.html">ToTtOnly</a></code></li><li><code><a href="./RDoc/Markup/Verbatim.html">Verbatim</a></code></li></ul></details></li><li><details><summary><code><a href="./RDoc/MarkupReference.html">MarkupReference</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/MarkupReference/DummyClass.html">DummyClass</a></code></li><li><code><a href="./RDoc/MarkupReference/DummyModule.html">DummyModule</a></code></li></ul></details></li><li><code><a href="./RDoc/MetaMethod.html">MetaMethod</a></code></li><li><code><a href="./RDoc/MethodAttr.html">MethodAttr</a></code></li><li><code><a href="./RDoc/Mixin.html">Mixin</a></code></li><li><code><a href="./RDoc/NormalClass.html">NormalClass</a></code></li><li><code><a href="./RDoc/NormalModule.html">NormalModule</a></code></li><li><code><a href="./RDoc/Options.html">Options</a></code></li><li><details><summary><code><a href="./RDoc/Parser.html">Parser</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Parser/C.html">C</a></code></li><li><details><summary><code><a href="./RDoc/Parser/ChangeLog.html">ChangeLog</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Parser/ChangeLog/Git.html">Git</a></code></li></ul></details></li><li><code><a href="./RDoc/Parser/Markdown.html">Markdown</a></code></li><li><code><a href="./RDoc/Parser/PrismRuby.html">PrismRuby</a></code></li><li><code><a href="./RDoc/Parser/RD.html">RD</a></code></li><li><code><a href="./RDoc/Parser/RipperStateLex.html">RipperStateLex</a></code></li><li><code><a href="./RDoc/Parser/Ruby.html">Ruby</a></code></li><li><code><a href="./RDoc/Parser/RubyTools.html">RubyTools</a></code></li><li><code><a href="./RDoc/Parser/Simple.html">Simple</a></code></li><li><code><a href="./RDoc/Parser/Text.html">Text</a></code></li></ul></details></li><li><details><summary><code><a href="./RDoc/RD.html">RD</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/RD/Inline.html">Inline</a></code></li></ul></details></li><li><code><a href="./RDoc/RDoc.html">RDoc</a></code></li><li><details><summary><code><a href="./RDoc/RI.html">RI</a></code></summary><ul class="link-list"><li><details><summary><code><a href="./RDoc/RI/Driver.html">Driver</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/RI/Driver/Error.html">Error</a></code></li><li><code><a href="./RDoc/RI/Driver/NotFoundError.html">NotFoundError</a></code></li></ul></details></li><li><code><a href="./RDoc/RI/Error.html">Error</a></code></li><li><code><a href="./RDoc/RI/Paths.html">Paths</a></code></li><li><code><a href="./RDoc/RI/Task.html">Task</a></code></li></ul></details></li><li><code><a href="./RDoc/Require.html">Require</a></code></li><li><code><a href="./RDoc/RubyGemsHook.html">RubyGemsHook</a></code></li><li><code><a href="./RDoc/RubygemsHook.html">RubygemsHook</a></code></li><li><code><a href="./RDoc/Servlet.html">Servlet</a></code></li><li><code><a href="./RDoc/SingleClass.html">SingleClass</a></code></li><li><details><summary><code><a href="./RDoc/Stats.html">Stats</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Stats/Normal.html">Normal</a></code></li><li><code><a href="./RDoc/Stats/Quiet.html">Quiet</a></code></li><li><code><a href="./RDoc/Stats/Verbose.html">Verbose</a></code></li></ul></details></li><li><details><summary><code><a href="./RDoc/Store.html">Store</a></code></summary><ul class="link-list"><li><code><a href="./RDoc/Store/Error.html">Error</a></code></li><li><code><a href="./RDoc/Store/MissingFileError.html">MissingFileError</a></code></li></ul></details></li><li><code><a href="./RDoc/Task.html">Task</a></code></li><li><code><a href="./RDoc/Text.html">Text</a></code></li><li><code><a href="./RDoc/TokenStream.html">TokenStream</a></code></li><li><code><a href="./RDoc/TomDoc.html">TomDoc</a></code></li><li><code><a href="./RDoc/TopLevel.html">TopLevel</a></code></li></ul></details></li></ul> </div> <footer id="validator-badges" role="contentinfo"> <p><a href="https://validator.w3.org/check/referer">Validate</a> <p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.12.0. <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>. </footer> </nav> <main role="main"> <h1 id="label-RDoc+-+Ruby+Documentation+System">RDoc - Ruby Documentation System<span><a href="#label-RDoc+-+Ruby+Documentation+System">¶</a> <a href="#top">↑</a></span></h1> <dl class="rdoc-list note-list"><dt>home </dt> <dd> <p><a href="https://github.com/ruby/rdoc">github.com/ruby/rdoc</a></p> </dd><dt>rdoc </dt> <dd> <p><a href="https://ruby.github.io/rdoc">ruby.github.io/rdoc</a></p> </dd><dt>bugs </dt> <dd> <p><a href="https://github.com/ruby/rdoc/issues">github.com/ruby/rdoc/issues</a></p> </dd><dt>code quality </dt> <dd> <p><a href="https://codeclimate.com/github/ruby/rdoc">codeclimate.com/github/ruby/rdoc</a></p> </dd></dl> <h2 id="label-Description">Description<span><a href="#label-Description">¶</a> <a href="#top">↑</a></span></h2> <p>RDoc produces HTML and command-line documentation for Ruby projects. RDoc includes the <code>rdoc</code> and <code>ri</code> tools for generating and displaying documentation from the command-line.</p> <h2 id="label-Generating+Documentation">Generating Documentation<span><a href="#label-Generating+Documentation">¶</a> <a href="#top">↑</a></span></h2> <p>Once installed, you can create documentation using the <code>rdoc</code> command</p> <pre>$ rdoc [options] [names...]</pre> <p>For an up-to-date option summary, type</p> <pre>$ rdoc --help</pre> <p>A typical use might be to generate documentation for a package of Ruby source (such as RDoc itself).</p> <pre>$ rdoc</pre> <p>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 <code>doc</code>.</p> <p>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</p> <pre>% rdoc --main README.rdoc</pre> <p>You’ll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.</p> <p>RDoc uses file extensions to determine how to process each file. File names ending <code>.rb</code> and <code>.rbw</code> are assumed to be Ruby source. Files ending <code>.c</code> 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.</p> <p>To generate documentation using <code>rake</code> see <a href="https://ruby.github.io/rdoc/RDoc/Task.html">RDoc::Task</a>.</p> <p>To generate documentation programmatically:</p> <pre class="ruby"><span class="ruby-identifier">gem</span> <span class="ruby-string">'rdoc'</span> <span class="ruby-identifier">require</span> <span class="ruby-string">'rdoc/rdoc'</span> <span class="ruby-identifier">options</span> = <span class="ruby-constant">RDoc</span><span class="ruby-operator">::</span><span class="ruby-constant">Options</span>.<span class="ruby-identifier">new</span> <span class="ruby-comment"># see RDoc::Options</span> <span class="ruby-identifier">rdoc</span> = <span class="ruby-constant">RDoc</span><span class="ruby-operator">::</span><span class="ruby-constant">RDoc</span>.<span class="ruby-identifier">new</span> <span class="ruby-identifier">rdoc</span>.<span class="ruby-identifier">document</span> <span class="ruby-identifier">options</span> <span class="ruby-comment"># see RDoc::RDoc</span> </pre> <p>You can specify the target files for document generation with <code>.document</code> file in the project root directory. <code>.document</code> file contains a list of file and directory names including comment lines starting with ‘#’. See <a href="https://github.com/ruby/rdoc/blob/master/.document">github.com/ruby/rdoc/blob/master/.document</a> as an example.</p> <h2 id="label-Writing+Documentation">Writing Documentation<span><a href="#label-Writing+Documentation">¶</a> <a href="#top">↑</a></span></h2> <p>To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:</p> <pre class="ruby"><span class="ruby-comment">##</span> <span class="ruby-comment"># This class represents an arbitrary shape by a series of points.</span> <span class="ruby-keyword">class</span> <span class="ruby-constant">Shape</span> <span class="ruby-comment">##</span> <span class="ruby-comment"># Creates a new shape described by a +polyline+.</span> <span class="ruby-comment">#</span> <span class="ruby-comment"># If the +polyline+ does not end at the same point it started at the</span> <span class="ruby-comment"># first pointed is copied and placed at the end of the line.</span> <span class="ruby-comment">#</span> <span class="ruby-comment"># An ArgumentError is raised if the line crosses itself, but shapes may</span> <span class="ruby-comment"># be concave.</span> <span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">initialize</span> <span class="ruby-identifier">polyline</span> <span class="ruby-comment"># ...</span> <span class="ruby-keyword">end</span> <span class="ruby-keyword">end</span> </pre> <p>The default comment markup format is the <a href="RDoc/Markup.html"><code>RDoc::Markup</code></a> format. <a href="RDoc/TomDoc.html">TomDoc</a>, <a href="RDoc/Markdown.html">Markdown</a> and <a href="RDoc/RD.html">RD</a> format comments are also supported. You can set the default comment format for your entire project by creating a <code>.rdoc_options</code> file. See <a href="RDoc/Options.html#class-RDoc::Options-label-Saved+Options">Saved Options at <code>RDoc::Options</code></a> for instructions on creating one. You can also set the comment format for a single file through the <code>:markup:</code> directive, but this is only recommended if you wish to switch markup formats. See <a href="RDoc/Markup.html#class-RDoc::Markup-label-Other+directives">Other directives at <code>RDoc::Markup</code></a>.</p> <p>Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing. See <a href="RDoc/Markup.html#class-RDoc::Markup-label-Directives">Directives at <code>RDoc::Markup</code></a> to control what is or is not documented, to define method arguments or to break up methods in a class by topic. See <a href="RDoc/Parser/Ruby.html"><code>RDoc::Parser::Ruby</code></a> for directives used to teach RDoc about metaprogrammed methods.</p> <p>See <a href="RDoc/Parser/C.html"><code>RDoc::Parser::C</code></a> for documenting C extensions with RDoc.</p> <p>To determine how well your project is documented run <code>rdoc -C lib</code> to get a documentation coverage report. <code>rdoc -C1 lib</code> includes parameter names in the documentation coverage report.</p> <h2 id="label-Theme+Options">Theme Options<span><a href="#label-Theme+Options">¶</a> <a href="#top">↑</a></span></h2> <p>There are a few community-maintained themes for RDoc:</p> <ul><li> <p><a href="https://github.com/BaseSecrete/rorvswild-theme-rdoc">rorvswild-theme-rdoc</a></p> </li><li> <p><a href="https://github.com/jeremyevans/hanna">hanna</a> (a fork maintained by <a href="https://github.com/jeremyevans">Jeremy Evans</a>)</p> </li></ul> <p>Please follow the theme’s README for usage instructions.</p> <h2 id="label-Bugs">Bugs<span><a href="#label-Bugs">¶</a> <a href="#top">↑</a></span></h2> <p>See Bugs at <code>CONTRIBUTING</code> 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.</p> <h2 id="label-License">License<span><a href="#label-License">¶</a> <a href="#top">↑</a></span></h2> <p>RDoc is Copyright © 2001-2003 Dave Thomas, The Pragmatic Programmers. Portions © 2007-2011 Eric Hodel. Portions copyright others, see individual files and <a href="LEGAL_rdoc.html">LEGAL.rdoc</a> for details.</p> <p>RDoc is free software, and may be redistributed under the terms specified in <a href="LICENSE_rdoc.html">LICENSE.rdoc</a>.</p> <h2 id="label-Warranty">Warranty<span><a href="#label-Warranty">¶</a> <a href="#top">↑</a></span></h2> <p>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.</p> </main>