mirror of
https://github.com/KevinMidboe/linguist.git
synced 2025-10-29 17:50:22 +00:00
130 lines
4.3 KiB
Plaintext
130 lines
4.3 KiB
Plaintext
= \RDoc - Ruby Documentation System
|
|
|
|
home :: https://github.com/rdoc/rdoc
|
|
rdoc :: http://docs.seattlerb.org/rdoc
|
|
bugs :: https://github.com/rdoc/rdoc/issues
|
|
code quality :: {<img src="https://codeclimate.com/badge.png" alt="code climate">}[https://codeclimate.com/github/rdoc/rdoc]
|
|
|
|
== Description
|
|
|
|
RDoc produces HTML and command-line documentation for Ruby projects. RDoc
|
|
includes the +rdoc+ and +ri+ tools for generating and displaying documentation
|
|
from the command-line.
|
|
|
|
== Generating Documentation
|
|
|
|
Once installed, you can create documentation using the +rdoc+ command
|
|
|
|
$ rdoc [options] [names...]
|
|
|
|
For an up-to-date option summary, type
|
|
|
|
$ rdoc --help
|
|
|
|
A typical use might be to generate documentation for a package of Ruby
|
|
source (such as RDoc itself).
|
|
|
|
$ rdoc
|
|
|
|
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 +doc+.
|
|
|
|
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
|
|
|
|
% rdoc --main README.rdoc
|
|
|
|
You'll find information on the various formatting tricks you can use
|
|
in comment blocks in the documentation this generates.
|
|
|
|
RDoc uses file extensions to determine how to process each file. File names
|
|
ending +.rb+ and +.rbw+ are assumed to be Ruby source. Files
|
|
ending +.c+ 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.
|
|
|
|
To generate documentation using +rake+ see RDoc::Task.
|
|
|
|
To generate documentation programmatically:
|
|
|
|
gem 'rdoc'
|
|
require 'rdoc/rdoc'
|
|
|
|
options = RDoc::Options.new
|
|
# see RDoc::Options
|
|
|
|
rdoc = RDoc::RDoc.new
|
|
rdoc.document options
|
|
# see RDoc::RDoc
|
|
|
|
== Writing Documentation
|
|
|
|
To write documentation for RDoc place a comment above the class, module,
|
|
method, constant, or attribute you want documented:
|
|
|
|
##
|
|
# This class represents an arbitrary shape by a series of points.
|
|
|
|
class Shape
|
|
|
|
##
|
|
# Creates a new shape described by a +polyline+.
|
|
#
|
|
# If the +polyline+ does not end at the same point it started at the
|
|
# first pointed is copied and placed at the end of the line.
|
|
#
|
|
# An ArgumentError is raised if the line crosses itself, but shapes may
|
|
# be concave.
|
|
|
|
def initialize polyline
|
|
# ...
|
|
end
|
|
|
|
end
|
|
|
|
The default comment markup format is the RDoc::Markup format.
|
|
TomDoc[rdoc-ref:RDoc::TomDoc], Markdown[rdoc-ref:RDoc::Markdown] and
|
|
RD[rdoc-ref:RDoc::RD] format comments are also supported. You can set the
|
|
default comment format for your entire project by creating a
|
|
<tt>.rdoc_options</tt> file. See RDoc::Options@Saved+Options for instructions
|
|
on creating one. You can also set the comment format for a single file
|
|
through the +:markup:+ directive, but this is only recommended if you wish to
|
|
switch markup formats. See RDoc::Markup@Other+directives.
|
|
|
|
Comments can contain directives that tell RDoc information that it cannot
|
|
otherwise discover through parsing. See RDoc::Markup@Directives to control
|
|
what is or is not documented, to define method arguments or to break up
|
|
methods in a class by topic. See RDoc::Parser::Ruby for directives used to
|
|
teach RDoc about metaprogrammed methods.
|
|
|
|
See RDoc::Parser::C for documenting C extensions with RDoc.
|
|
|
|
To determine how well your project is documented run <tt>rdoc -C lib</tt> to
|
|
get a documentation coverage report. <tt>rdoc -C1 lib</tt> includes parameter
|
|
names in the documentation coverage report.
|
|
|
|
== Bugs
|
|
|
|
See CONTRIBUTING@Bugs 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.
|
|
|
|
== License
|
|
|
|
RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.
|
|
Portions (c) 2007-2011 Eric Hodel. Portions copyright others, see individual
|
|
files and LEGAL.rdoc for details.
|
|
|
|
RDoc is free software, and may be redistributed under the terms specified in
|
|
LICENSE.rdoc.
|
|
|
|
== Warranty
|
|
|
|
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.
|