From f8c7b41165042b3d398a6a237aac9207e2856aea Mon Sep 17 00:00:00 2001 From: dave Date: Tue, 20 Jan 2004 05:04:31 +0000 Subject: [PATCH] Document lib/English. Add top-level aliases to rdoc html output git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5512 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 7 + lib/English.rb | 137 ++++++++++++++++++ lib/rdoc/generators/html_generator.rb | 12 +- lib/rdoc/generators/template/html/html.rb | 16 +- lib/rdoc/generators/template/html/old_html.rb | 44 +----- lib/rdoc/parsers/parse_rb.rb | 1 + 6 files changed, 172 insertions(+), 45 deletions(-) diff --git a/ChangeLog b/ChangeLog index 7fa2d41a60..8272c2f12e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Tue Jan 20 13:22:39 2004 Dave Thomas + + * lib/rdoc/generators/html_generator.rb: Document aliases at + top-most level. + + * lib/English.rb: Document English.rb. + Tue Jan 20 04:41:58 2004 Nobuyoshi Nakada * test/ruby/test_marshal.rb (MarshalTestLib::test_exception): test diff --git a/lib/English.rb b/lib/English.rb index 625b035270..4b859d96f6 100644 --- a/lib/English.rb +++ b/lib/English.rb @@ -1,27 +1,164 @@ +# Include the English library file in a Ruby script, and you can +# reference the global variables such as \VAR{\$\_} using less +# cryptic names, listed in the following table.% \vref{tab:english}. +# +# Without 'English': +# +# $\ = ' -- ' +# "waterbuffalo" =~ /buff/ +# print $", $', $$, "\n" +# +# With English: +# +# require "English" +# +# $OUTPUT_FIELD_SEPARATOR = ' -- ' +# "waterbuffalo" =~ /buff/ +# print $LOADED_FEATURES, $POSTMATCH, $PID, "\n" + + +# The exception object passed to +raise+. alias $ERROR_INFO $! + +# The stack backtrace generated by the last +# exception. See Kernel.caller for details. Thread local. alias $ERROR_POSITION $@ + +# An array containing the filenames of modules loaded by +require+. alias $LOADED_FEATURES $" + +# The default separator pattern used by String.split. May be +# set from the command line using the -F flag. alias $FS $; + +# The default separator pattern used by String.split. May be +# set from the command line using the -F flag. alias $FIELD_SEPARATOR $; + +# The separator string output between the parameters to methods such +# as Kernel.print and Array.join. Defaults to +nil+, +# which adds no text. alias $OFS $, + +# The separator string output between the parameters to methods such +# as Kernel.print and Array.join. Defaults to +nil+, +# which adds no text. alias $OUTPUT_FIELD_SEPARATOR $, + +# The input record separator (newline by default). This is the value +# that routines such as Kernel.gets use to determine record +# boundaries. If set to +nil+, +gets+ will read the entire file. alias $RS $/ + +# The input record separator (newline by default). This is the value +# that routines such as Kernel.gets use to determine record +# boundaries. If set to +nil+, +gets+ will read the entire file. alias $INPUT_RECORD_SEPARATOR $/ + +# The string appended to the output of every call to methods such as +# Kernel.print and IO.write. The default value is +# +nil+. alias $ORS $\ + +# The string appended to the output of every call to methods such as +# Kernel.print and IO.write. The default value is +# +nil+. alias $OUTPUT_RECORD_SEPARATOR $\ + +# The number of the last line read from the current input file. alias $INPUT_LINE_NUMBER $. + +# The number of the last line read from the current input file. alias $NR $. + +# The last line read by Kernel.gets or +# Kernel.readline. Many string-related functions in the +# +Kernel+ module operate on $_ by default. The variable is +# local to the current scope. Thread local. alias $LAST_READ_LINE $_ + +# The destination of output for Kernel.print +# and Kernel.printf. The default value is +# $stdout. alias $DEFAULT_OUTPUT $> + +# An object that provides access to the concatenation +# of the contents of all the files +# given as command-line arguments, or $stdin +# (in the case where there are no +# arguments). $< supports methods similar to a +# +File+ object: +# +inmode+, +close+, +# closed?, +each+, +# each_byte, each_line, +# +eof+, eof?, +file+, +# +filename+, +fileno+, +# +getc+, +gets+, +lineno+, +# lineno=, +path+, +# +pos+, pos=, +# +read+, +readchar+, +# +readline+, +readlines+, +# +rewind+, +seek+, +skip+, +# +tell+, to_a, to_i, +# to_io, to_s, along with the +# methods in +Enumerable+. The method +file+ +# returns a +File+ object for the file currently +# being read. This may change as $< reads +# through the files on the command line. Read only. alias $DEFAULT_INPUT $< + +# The process number of the program being executed. Read only. alias $PID $$ + +# The process number of the program being executed. Read only. alias $PROCESS_ID $$ + +# The exit status of the last child process to terminate. Read +# only. Thread local. alias $CHILD_STATUS $? + +# A +MatchData+ object that encapsulates the results of a successful +# pattern match. The variables $&, $`, $', +# and $1 to $9 are all derived from +# $~. Assigning to $~ changes the values of these +# derived variables. This variable is local to the current +# scope. Thread local. alias $LAST_MATCH_INFO $~ + +# If set to any value apart from +nil+ or +false+, all pattern matches +# will be case insensitive, string comparisons will ignore case, and +# string hash values will be case insensitive. Deprecated alias $IGNORECASE $= + +# The name of the top-level Ruby program being executed. Typically +# this will be the program's filename. On some operating systems, +# assigning to this variable will change the name of the process +# reported (for example) by the ps(1) command. alias $PROGRAM_NAME $0 + +# An array of strings containing the command-line +# options from the invocation of the program. Options +# used by the Ruby interpreter will have been +# removed. Read only. Also known simply as +ARGV+. alias $ARGV $* + +# The string matched by the last successful pattern +# match. This variable is local to the current +# scope. Read only. Thread local. alias $MATCH $& + +# The string preceding the match in the last +# successful pattern match. This variable is local to +# the current scope. Read only. Thread local. alias $PREMATCH $` + +# The string following the match in the last +# successful pattern match. This variable is local to +# the current scope. Read only. Thread local. alias $POSTMATCH $' + +# The contents of the highest-numbered group matched in the last +# successful pattern match. Thus, in "cat" =~ /(c|a)(t|z)/, +# $+ will be set to "t". This variable is local to the +# current scope. Read only. Thread local. alias $LAST_PAREN_MATCH $+ diff --git a/lib/rdoc/generators/html_generator.rb b/lib/rdoc/generators/html_generator.rb index b5e8f24e43..994d74b103 100644 --- a/lib/rdoc/generators/html_generator.rb +++ b/lib/rdoc/generators/html_generator.rb @@ -326,13 +326,18 @@ module Generators end - # Build a list of aliases fo which we couldn't find a corresponding method + # Build a list of aliases for which we couldn't find a + # corresponding method def build_alias_summary_list @context.aliases.map do |al| - { + res = { 'old_name' => al.old_name, 'new_name' => al.new_name, } + if al.comment && !al.comment.empty? + res['desc'] = markup(al.comment, true) + end + res end end @@ -750,6 +755,9 @@ module Generators co = build_constants_summary_list @values["constants"] = co unless co.empty? + al = build_alias_summary_list + @values["aliases"] = al unless al.empty? + if @options.promiscuous file_context = nil else diff --git a/lib/rdoc/generators/template/html/html.rb b/lib/rdoc/generators/template/html/html.rb index 8ac631490c..16955f550a 100644 --- a/lib/rdoc/generators/template/html/html.rb +++ b/lib/rdoc/generators/template/html/html.rb @@ -324,9 +324,21 @@ IF:aliases

External Aliases

+ START:aliases - %old_name% -> %new_name%
+ + + + + +IF:desc + + + + +ENDIF:desc END:aliases +
%old_name%->%new_name%
 %desc%
ENDIF:aliases @@ -630,6 +642,8 @@ INDEX = %{ } + end # module Page end # class RDoc +require 'rdoc/generators/template/html/one_page_html' diff --git a/lib/rdoc/generators/template/html/old_html.rb b/lib/rdoc/generators/template/html/old_html.rb index 3398dc808f..de19b66967 100644 --- a/lib/rdoc/generators/template/html/old_html.rb +++ b/lib/rdoc/generators/template/html/old_html.rb @@ -721,48 +721,8 @@ END:method_list ENDIF:method_list } -######################################################################## - -ONE_PAGE = %{ - - - - %title% - - - -START:files -

File: %short_name%

- - - -
Path:%full_path%
Modified:%dtm_modified%
-} + CONTENTS_XML + %{ -END:files - -IF:classes -

Classes

-START:classes -IF:parent -

%classmod% %full_name% < HREF:par_url:parent:

-ENDIF:parent -IFNOT:parent -

%classmod% %full_name%

-ENDIF:parent - -IF:infiles -(in files -START:infiles -HREF:full_path_url:full_path: -END:infiles -) -ENDIF:infiles -} + CONTENTS_XML + %{ -END:classes -ENDIF:classes - - -} end end + +require 'rdoc/generators/template/html/one_page_html' diff --git a/lib/rdoc/parsers/parse_rb.rb b/lib/rdoc/parsers/parse_rb.rb index d050829915..413167a39a 100644 --- a/lib/rdoc/parsers/parse_rb.rb +++ b/lib/rdoc/parsers/parse_rb.rb @@ -2313,6 +2313,7 @@ module RDoc skip_tkspace end old_name = get_symbol_or_name + al = Alias.new(get_tkread, old_name, new_name, comment) read_documentation_modifiers(al, ATTR_MODIFIERS) if al.document_self