mirror of
https://github.com/KevinMidboe/linguist.git
synced 2025-10-29 17:50:22 +00:00
Revert "Merge pull request #695 from github/detect-prose"
This reverts commit80321272b1, reversing changes made to02500d3830.
This commit is contained in:
Ted Nyman
@@ -1,129 +0,0 @@
|
||||
= \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.
|
||||
Reference in New Issue
Block a user