Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 130 lines (91 sloc) 4.436 kb
54dbcf7 @drbrain Import various improvements from Thierry Lambert. See History.txt.
drbrain authored
1 = \RDoc - Ruby Documentation System
7f2389d @drbrain Hoeify. Make tests pass on 1.8 and 1.9.
drbrain authored
2
9b48be3 @drbrain Change readme to linkable titles
drbrain authored
3 home :: https://github.com/rdoc/rdoc
4 rdoc :: http://docs.seattlerb.org/rdoc
5 bugs :: https://github.com/rdoc/rdoc/issues
9351718 @drbrain Add alt= for HTML 5 validation
drbrain authored
6 code quality :: {<img src="https://codeclimate.com/badge.png" alt="code climate">}[https://codeclimate.com/github/rdoc/rdoc]
7f2389d @drbrain Hoeify. Make tests pass on 1.8 and 1.9.
drbrain authored
7
9b48be3 @drbrain Change readme to linkable titles
drbrain authored
8 == Description
53324b7 @drbrain Update release notes type files.
drbrain authored
9
9965899 @drbrain Minor updates to README.txt
drbrain authored
10 RDoc produces HTML and command-line documentation for Ruby projects. RDoc
50be8bd @drbrain Reorganized and improved documentation around choosing a default comment...
drbrain authored
11 includes the +rdoc+ and +ri+ tools for generating and displaying documentation
12 from the command-line.
53324b7 @drbrain Update release notes type files.
drbrain authored
13
50be8bd @drbrain Reorganized and improved documentation around choosing a default comment...
drbrain authored
14 == Generating Documentation
7f1add6 @DesigningPatterns Change the Rakefile so that documentation will be published to the root ...
DesigningPatterns authored
15
50be8bd @drbrain Reorganized and improved documentation around choosing a default comment...
drbrain authored
16 Once installed, you can create documentation using the +rdoc+ command
0bd431e @drbrain Update README.
drbrain authored
17
50be8bd @drbrain Reorganized and improved documentation around choosing a default comment...
drbrain authored
18 $ rdoc [options] [names...]
9965899 @drbrain Minor updates to README.txt
drbrain authored
19
50be8bd @drbrain Reorganized and improved documentation around choosing a default comment...
drbrain authored
20 For an up-to-date option summary, type
09b5c6f @drbrain Add more links to README.txt, make some corrections to RDoc's documentat...
drbrain authored
21
50be8bd @drbrain Reorganized and improved documentation around choosing a default comment...
drbrain authored
22 $ rdoc --help
23
24 A typical use might be to generate documentation for a package of Ruby
25 source (such as RDoc itself).
26
27 $ rdoc
28
29 This command generates documentation for all the Ruby and C source
30 files in and below the current directory. These will be stored in a
31 documentation tree starting in the subdirectory +doc+.
32
33 You can make this slightly more useful for your readers by having the
34 index page contain the documentation for the primary file. In our
35 case, we could type
36
37 % rdoc --main README.rdoc
38
39 You'll find information on the various formatting tricks you can use
40 in comment blocks in the documentation this generates.
41
42 RDoc uses file extensions to determine how to process each file. File names
43 ending +.rb+ and +.rbw+ are assumed to be Ruby source. Files
44 ending +.c+ are parsed as C files. All other files are assumed to
45 contain just Markup-style markup (with or without leading '#' comment
46 markers). If directory names are passed to RDoc, they are scanned
47 recursively for C and Ruby source files only.
09b5c6f @drbrain Add more links to README.txt, make some corrections to RDoc's documentat...
drbrain authored
48
49 To generate documentation using +rake+ see RDoc::Task.
9965899 @drbrain Minor updates to README.txt
drbrain authored
50
51 To generate documentation programmatically:
52
0bd431e @drbrain Update README.
drbrain authored
53 gem 'rdoc'
54 require 'rdoc/rdoc'
09b5c6f @drbrain Add more links to README.txt, make some corrections to RDoc's documentat...
drbrain authored
55
56 options = RDoc::Options.new
57 # see RDoc::Options
58
59 rdoc = RDoc::RDoc.new
60 rdoc.document options
61 # see RDoc::RDoc
0bd431e @drbrain Update README.
drbrain authored
62
50be8bd @drbrain Reorganized and improved documentation around choosing a default comment...
drbrain authored
63 == Writing Documentation
64
65 To write documentation for RDoc place a comment above the class, module,
66 method, constant, or attribute you want documented:
67
68 ##
69 # This class represents an arbitrary shape by a series of points.
70
71 class Shape
72
73 ##
74 # Creates a new shape described by a +polyline+.
75 #
76 # If the +polyline+ does not end at the same point it started at the
77 # first pointed is copied and placed at the end of the line.
78 #
79 # An ArgumentError is raised if the line crosses itself, but shapes may
80 # be concave.
81
82 def initialize polyline
83 # ...
84 end
85
86 end
87
88 The default comment markup format is the RDoc::Markup format.
89 TomDoc[rdoc-ref:RDoc::TomDoc], Markdown[rdoc-ref:RDoc::Markdown] and
90 RD[rdoc-ref:RDoc::RD] format comments are also supported. You can set the
91 default comment format for your entire project by creating a
92 <tt>.rdoc_options</tt> file. See RDoc::Options@Saved+Options for instructions
93 on creating one. You can also set the comment format for a single file
94 through the +:markup:+ directive, but this is only recommended if you wish to
95 switch markup formats. See RDoc::Markup@Other+directives.
96
97 Comments can contain directives that tell RDoc information that it cannot
98 otherwise discover through parsing. See RDoc::Markup@Directives to control
99 what is or is not documented, to define method arguments or to break up
100 methods in a class by topic. See RDoc::Parser::Ruby for directives used to
101 teach RDoc about metaprogrammed methods.
102
103 See RDoc::Parser::C for documenting C extensions with RDoc.
104
105 To determine how well your project is documented run <tt>rdoc -C lib</tt> to
106 get a documentation coverage report. <tt>rdoc -C1 lib</tt> includes parameter
107 names in the documentation coverage report.
108
9b48be3 @drbrain Change readme to linkable titles
drbrain authored
109 == Bugs
3f51d6f @drbrain Update README.txt
drbrain authored
110
796120d @drbrain Rename DEVELOPERS to CONTRIBUTING
drbrain authored
111 See CONTRIBUTING@Bugs for information on filing a bug report. It's OK to file
112 a bug report for anything you're having a problem with. If you can't figure
113 out how to make RDoc produce the output you like that is probably a
114 documentation bug.
935425d @drbrain Add BUGS section, set History numbers.
drbrain authored
115
9b48be3 @drbrain Change readme to linkable titles
drbrain authored
116 == License
53324b7 @drbrain Update release notes type files.
drbrain authored
117
3f51d6f @drbrain Update README.txt
drbrain authored
118 RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.
897119b @drbrain Update URLs
drbrain authored
119 Portions (c) 2007-2011 Eric Hodel. Portions copyright others, see individual
c74de82 @drbrain RDoc::Markdown now passes MarkdownTest
drbrain authored
120 files and LEGAL.rdoc for details.
3f51d6f @drbrain Update README.txt
drbrain authored
121
c74de82 @drbrain RDoc::Markdown now passes MarkdownTest
drbrain authored
122 RDoc is free software, and may be redistributed under the terms specified in
123 LICENSE.rdoc.
54dbcf7 @drbrain Import various improvements from Thierry Lambert. See History.txt.
drbrain authored
124
9b48be3 @drbrain Change readme to linkable titles
drbrain authored
125 == Warranty
54dbcf7 @drbrain Import various improvements from Thierry Lambert. See History.txt.
drbrain authored
126
127 This software is provided "as is" and without any express or implied
128 warranties, including, without limitation, the implied warranties of
51820d5 @drbrain Fixed various typos discovered by rdoc-spellcheck
drbrain authored
129 merchantability and fitness for a particular purpose.
Something went wrong with that request. Please try again.