Skip to content
Browse files

Further improvement's to RDoc's documentation in prepration for RDoc …

…2.2.0.
  • Loading branch information...
1 parent 5793f5b commit 8e801adfde3523bba6e4bcf9f2c55c0ecfbbff5c designingpatts committed Sep 17, 2008
Showing with 49 additions and 46 deletions.
  1. +2 −1 History.txt
  2. +2 −2 README.txt
  3. +13 −11 RI.txt
  4. +32 −32 lib/rdoc.rb
View
3 History.txt
@@ -19,7 +19,7 @@ documentation about ri.
unqualified methods if more than one is present and also will allow a
user to get information for a class' method.
-* 6 Minor Enhancements
+* 7 Minor Enhancements
* RDoc now adds the package title to the web pages that it generates
for files and classes/modules, which helps them appear better in
search engine results.
@@ -31,6 +31,7 @@ documentation about ri.
* Improved rdoc's HTML generation speed by about 20% (on Windows, the
boost seems larger).
* Provided an ri command-line option to control its caching behavior.
+ * Improved RDoc's documentation. Added RI.txt to document ri.
* 24 Bug fixes:
* Fixed prototype detection in C parser. Can process ruby 1.8 C files
View
4 README.txt
@@ -6,7 +6,7 @@
== DESCRIPTION:
RDoc is an application that produces documentation for one or more Ruby source
-files. RDoc includes the `rdoc` and `ri` tools for generating and displaying
+files. RDoc includes the +rdoc+ and +ri+ tools for generating and displaying
online documentation.
At this point in time, RDoc 2.x is a work in progress and may incur further
@@ -23,7 +23,7 @@ template is Hanna[http://github.com/mislav/hanna/tree/master].
We strongly are considering making Hanna as RDoc's default template
in a future release, but for now this template can be downloaded separately
-and used with the -T option.
+and used with the +-T+ option.
== SYNOPSIS:
View
24 RI.txt
@@ -4,40 +4,40 @@
It is part of RDoc and is expected to work on any platform supported by Ruby.
+ri+ will be a bit slow the first time that it runs (or any time that the
-underlying documentation changes) because it builds a cache in the .ri
+underlying documentation changes) because it builds a cache in the +.ri+
directory within the user's home directory in order to make future accesses
-more efficient.
+faster.
== Usage
To see information for a class, do:
ri class_name
-For example, for the Array class, do
+For example, for the +Array+ class, do
ri Array
-To see information for an instance method,e do:
+To see information for an instance method, do:
ri class_name#method_name
-For example, for Array's join method, do:
+For example, for Array's +join+ method, do:
ri Array#join
To see information for a class method, do:
ri class_name.method_name
-For example, for Module's private method, do:
+For example, for Module's +private+ method, do:
ri Module.private
-To search for all methods containing 'read', do:
+To search for all methods containing +read+, do:
ri read
-To search for all methods starting with 'read', do:
+To search for all methods starting with +read+, do:
ri '^read'
-To search for all 'read' methods, do:
+To search for all +read+ methods, do:
ri '^read$'
== Options
-+ri+ supports a variety of options, all of which can be viewed via --help.
++ri+ supports a variety of options, all of which can be viewed via +--help+.
Of particular interest, are:
[-d directory]
List of directories from which to source documentation in addition to
@@ -51,6 +51,8 @@ Of particular interest, are:
to enter in a method name (with auto-completion, if readline is supported)
when viewing a class.
[-T]
- Send output to stdout, rather than to a page.
+ Send output to stdout, rather than to a pager.
All options also can be specified through the +RI+ environment variable.
+Command-line options always override those specified in the +RI+ environment
+variable.
View
64 lib/rdoc.rb
@@ -4,11 +4,11 @@
# = \RDoc - Ruby Documentation System
#
# This package contains RDoc and RDoc::Markup. RDoc is an application that
-# produces documentation for one or more Ruby source files. We work similarly
+# produces documentation for one or more Ruby source files. It works similarly
# to JavaDoc, parsing the source, and extracting the definition for classes,
-# modules, and methods (along with includes and requires). We associate with
+# modules, and methods (along with includes and requires). It associates with
# these optional documentation contained in the immediately preceding comment
-# block, and then render the result using a pluggable output formatter.
+# block, and then renders the result using a pluggable output formatter.
# RDoc::Markup is a library that converts plain text into various output
# formats. The markup library is used to interpret the comment blocks that
# RDoc uses to document methods, classes, and so on.
@@ -26,21 +26,21 @@
#
# == Summary
#
-# Once installed, you can create documentation using the 'rdoc' command
-# (the command is 'rdoc.bat' under Windows)
+# Once installed, you can create documentation using the +rdoc+ command
#
# % rdoc [options] [names...]
#
-# Type "rdoc --help" for an up-to-date option summary.
+# 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).
+# 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'.
+# 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
@@ -52,7 +52,7 @@
# in comment blocks in the documentation this generates.
#
# RDoc uses file extensions to determine how to process each file. File names
-# ending +.rb+ and <tt>.rbw</tt> are assumed to be Ruby source. Files
+# 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
@@ -89,9 +89,9 @@
#
# == Documenting Source Code
#
-# Comment blocks can be written fairly naturally, either using '#' on
+# Comment blocks can be written fairly naturally, either using +#+ on
# successive lines of the comment, or by including the comment in
-# an =begin/=end block. If you use the latter form, the =begin line must be
+# a =begin/=end block. If you use the latter form, the =begin line must be
# flagged with an RDoc tag:
#
# =begin rdoc
@@ -117,7 +117,7 @@
# # ...
# end
#
-# Names of classes, source files, and any method names containing an
+# Names of classes, files, and any method names containing an
# underscore or preceded by a hash character are automatically hyperlinked
# from comment text to their description.
#
@@ -159,7 +159,7 @@
# * If a paragraph starts with a "*", "-", or with "<digit>.", then it is
# taken to be the start of a list. The margin in increased to be the first
# non-space following the list start flag. Subsequent lines should be
-# indented to this \new margin until the list ends. For example:
+# indented to this new margin until the list ends. For example:
#
# * this is a list with three paragraphs in
# the first item. This is the first paragraph.
@@ -223,7 +223,7 @@
#
# [\<b>text...</b>] displays word in a *bold* font
# [\<em>text...</em>] displays word in an _emphasized_ font
-# [\<i>text...</i>] displays word in an _emphasized_ font
+# [\\<i>text...</i>] displays word in an <i>italicized</i> font
# [\<tt>text...</tt>] displays word in a +code+ font
#
# Unlike conventional Wiki markup, general markup can cross line
@@ -239,19 +239,19 @@
# directory.
#
# Hyperlinks can also be of the form <tt>label</tt>[url], in which
-# case the label is used in the displayed text, and <tt>url</tt> is
-# used as the target. If <tt>label</tt> contains multiple words,
+# case the label is used in the displayed text, and +url+ is
+# used as the target. If +label+ contains multiple words,
# put it in braces: <em>{multi word label}[</em>url<em>]</em>.
#
# == Directives
#
# [+:nodoc:+ / +:nodoc:+ all]
-# Don't include this element in the documentation. For classes
-# and modules, the methods, aliases, constants, and attributes
-# directly within the affected class or module will also be
-# omitted. By default, though, modules and classes within that
-# class of module _will_ be documented. This is turned off by
-# adding the +all+ modifier.
+# This directive prevents documentation for the element from
+# being generated. For classes and modules, the methods, aliases,
+# constants, and attributes directly within the affected class or
+# module also will be omitted. By default, though, modules and
+# classes within that class of module _will_ be documented. This is
+# turned off by adding the +all+ modifier.
#
# module MyModule # :nodoc:
# class Input
@@ -263,22 +263,22 @@
# end
# end
#
-# In the above code, only class +MyModule::Input+ will be documented.The
-# The :nodoc: directive is global across all files the class or module
-# appears in, so use :stopdoc:/:startdoc: to only omit documentation for a
-# particular set of methods, etc.
+# In the above code, only class <tt>MyModule::Input</tt> will be documented.
+# The +:nodoc:+ directive is global across all files for the class or module
+# to which it applies, so use +:stopdoc:+/+:startdoc:+ to suppress
+# documentation only for a particular set of methods, etc.
#
# [+:doc:+]
-# Force a method or attribute to be documented even if it wouldn't otherwise
-# be. Useful if, for example, you want to include documentation of a
+# Forces a method or attribute to be documented even if it wouldn't be
+# otherwise. Useful if, for example, you want to include documentation of a
# particular private method.
#
# [+:notnew:+]
# Only applicable to the +initialize+ instance method. Normally RDoc
-# assumes that the documentation and parameters for #initialize are
-# actually for the ::new method, and so fakes out a ::new for the class.
-# The :notnew: modifier stops this. Remember that #initialize is protected,
-# so you won't see the documentation unless you use the -a command line
+# assumes that the documentation and parameters for +initialize+ are
+# actually for the +new+ method, and so fakes out a +new+ for the class.
+# The +:notnew:+ modifier stops this. Remember that +initialize+ is private,
+# so you won't see the documentation unless you use the +-a+ command line
# option.
#
# Comment blocks can contain other directives:

0 comments on commit 8e801ad

Please sign in to comment.
Something went wrong with that request. Please try again.