diff options
author | dave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2004-01-02 06:01:12 +0000 |
---|---|---|
committer | dave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2004-01-02 06:01:12 +0000 |
commit | 88c127c19be3d12bc5edcb6ceb416985258396c6 (patch) | |
tree | c2d59557f5341202c22bf05448bebaad3df40a19 /lib/rdoc | |
parent | eee1377a60de602723599d313e1379ba7d875add (diff) |
Finish documenting internal stuff. See Changelog for other details
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5364 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/rdoc')
-rw-r--r-- | lib/rdoc/code_objects.rb | 6 | ||||
-rw-r--r-- | lib/rdoc/generators/ri_generator.rb | 4 | ||||
-rw-r--r-- | lib/rdoc/parsers/parse_c.rb | 9 | ||||
-rw-r--r-- | lib/rdoc/parsers/parse_f95.rb | 3 | ||||
-rw-r--r-- | lib/rdoc/parsers/parse_rb.rb | 7 | ||||
-rw-r--r-- | lib/rdoc/parsers/parse_simple.rb | 2 | ||||
-rw-r--r-- | lib/rdoc/parsers/parserfactory.rb | 5 | ||||
-rw-r--r-- | lib/rdoc/rdoc.rb | 73 | ||||
-rw-r--r-- | lib/rdoc/ri/ri_descriptions.rb | 14 | ||||
-rw-r--r-- | lib/rdoc/ri/ri_formatter.rb | 25 | ||||
-rw-r--r-- | lib/rdoc/ri/ri_options.rb | 35 |
11 files changed, 132 insertions, 51 deletions
diff --git a/lib/rdoc/code_objects.rb b/lib/rdoc/code_objects.rb index f5b4e81853..a8c3752cb8 100644 --- a/lib/rdoc/code_objects.rb +++ b/lib/rdoc/code_objects.rb @@ -263,6 +263,11 @@ module RDoc return self if self.name == name res = @modules[name] || @classes[name] return res if res + find_enclosing_module_named(name) + end + + # find a module at a higher scope + def find_enclosing_module_named(name) parent && parent.find_module_named(name) end @@ -316,6 +321,7 @@ module RDoc if result modules.each do |module_name| result = result.find_module_named(module_name) + break unless result end end end diff --git a/lib/rdoc/generators/ri_generator.rb b/lib/rdoc/generators/ri_generator.rb index 705ad7da06..8d94579347 100644 --- a/lib/rdoc/generators/ri_generator.rb +++ b/lib/rdoc/generators/ri_generator.rb @@ -97,10 +97,10 @@ module Generators def generate_class_info(cls) if cls === RDoc::NormalModule + cls_desc = RI::ModuleDescription.new + else cls_desc = RI::ClassDescription.new cls_desc.superclass = cls.superclass - else - cls_desc = RI::ModuleDescription.new end cls_desc.name = cls.name cls_desc.full_name = cls.full_name diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb index 4aca5eeb67..904aeb9417 100644 --- a/lib/rdoc/parsers/parse_c.rb +++ b/lib/rdoc/parsers/parse_c.rb @@ -127,13 +127,14 @@ module RDoc @@known_bodies = {} # prepare to parse a C file - def initialize(top_level, file_name, body, options) + def initialize(top_level, file_name, body, options, stats) @known_classes = KNOWN_CLASSES.dup @body = body @options = options + @stats = stats @top_level = top_level @classes = Hash.new - @file_dir = File.dirname(file_name) + @file_dir = File.dirname(file_name) end # Extract the classes/modules and methods from a C file @@ -173,8 +174,10 @@ module RDoc if class_mod == "class" cm = enclosure.add_class(NormalClass, class_name, parent_name) + @stats.num_classes += 1 else cm = enclosure.add_module(NormalModule, class_name) + @stats.num_modules += 1 end cm.record_location(enclosure.toplevel) @@ -302,6 +305,8 @@ module RDoc def handle_method(type, var_name, meth_name, meth_body, param_count, source_file = nil) + + @stats.num_methods += 1 class_name = @known_classes[var_name] || var_name class_obj = find_class(var_name, class_name) diff --git a/lib/rdoc/parsers/parse_f95.rb b/lib/rdoc/parsers/parse_f95.rb index 3adf29d933..518e421c60 100644 --- a/lib/rdoc/parsers/parse_f95.rb +++ b/lib/rdoc/parsers/parse_f95.rb @@ -32,8 +32,9 @@ module RDoc parse_files_matching(/\.(f9(0|5)|F)$/) # prepare to parse a Fortran 95 file - def initialize(top_level, file_name, body, options) + def initialize(top_level, file_name, body, options, stats) @body = body + @stats = stats @options = options @top_level = top_level @progress = $stderr unless options.quiet diff --git a/lib/rdoc/parsers/parse_rb.rb b/lib/rdoc/parsers/parse_rb.rb index 380025ef8d..b8044c119b 100644 --- a/lib/rdoc/parsers/parse_rb.rb +++ b/lib/rdoc/parsers/parse_rb.rb @@ -1374,8 +1374,9 @@ module RDoc parse_files_matching(/\.rbw?$/) - def initialize(top_level, file_name, content, options) + def initialize(top_level, file_name, content, options, stats) @options = options + @stats = stats @size = 0 @token_listeners = nil @input_file_name = file_name @@ -1710,6 +1711,8 @@ module RDoc def parse_class(container, single, tk, comment, &block) progress("c") + @stats.num_classes += 1 + container, name_t = get_class_or_module(container) case name_t @@ -1762,6 +1765,7 @@ module RDoc def parse_module(container, single, tk, comment) progress("m") + @stats.num_modules += 1 container, name_t = get_class_or_module(container) # skip_tkspace name = name_t.name @@ -1853,6 +1857,7 @@ module RDoc def parse_method(container, single, tk, comment) progress(".") + @stats.num_methods += 1 line_no = tk.line_no column = tk.char_no diff --git a/lib/rdoc/parsers/parse_simple.rb b/lib/rdoc/parsers/parse_simple.rb index 754f650793..b01104574e 100644 --- a/lib/rdoc/parsers/parse_simple.rb +++ b/lib/rdoc/parsers/parse_simple.rb @@ -12,7 +12,7 @@ module RDoc class SimpleParser # prepare to parse a plain file - def initialize(top_level, file_name, body, options) + def initialize(top_level, file_name, body, options, stats) preprocess = SM::PreProcess.new(file_name, options.rdoc_include) diff --git a/lib/rdoc/parsers/parserfactory.rb b/lib/rdoc/parsers/parserfactory.rb index dc7d629903..b19bd0ca9b 100644 --- a/lib/rdoc/parsers/parserfactory.rb +++ b/lib/rdoc/parsers/parserfactory.rb @@ -73,14 +73,15 @@ module RDoc # Find the correct parser for a particular file name. Return a # SimpleParser for ones that we don't know - def ParserFactory.parser_for(top_level, file_name, body, options) + def ParserFactory.parser_for(top_level, file_name, body, options, stats) parser_description = can_parse(file_name) if parser_description parser = parser_description.parser else parser = SimpleParser end - parser.new(top_level, file_name, body, options) + + parser.new(top_level, file_name, body, options, stats) end end end diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb index ca9c5da2bf..ddcf217c4b 100644 --- a/lib/rdoc/rdoc.rb +++ b/lib/rdoc/rdoc.rb @@ -31,6 +31,27 @@ require 'ftools' module RDoc + # Name of the dotfile that contains the description of files to be + # processed in the current directory + DOT_DOC_FILENAME = ".document" + + # Simple stats collector + class Stats + attr_accessor :num_files, :num_classes, :num_modules, :num_methods + def initialize + @num_files = @num_classes = @num_modules = @num_methods = 0 + @start = Time.now + end + def print + puts "Files: #@num_files" + puts "Classes: #@num_classes" + puts "Modules: #@num_modules" + puts "Methods: #@num_methods" + puts "Elapsed: " + sprintf("%0.3fs", Time.now - @start) + end + end + + # Exception thrown by any rdoc error. Only the #message part is # of use externally. @@ -110,25 +131,40 @@ module RDoc end + # The .document file contains a list of file and directory name + # patterns, representing candidates for documentation. It may + # also contain comments (starting with '#') + def parse_dot_doc_file(in_dir, filename, options) + # read and strip comments + patterns = File.read(filename).gsub(/#.*/, '') + + result = [] + + patterns.split.each do |patt| + candidates = Dir.glob(File.join(in_dir, patt)) + result.concat(normalized_file_list(options, candidates)) + end + result + end + + # Given a list of files and directories, create a list # of all the Ruby files they contain. - def normalized_file_list(options, *relative_files) + def normalized_file_list(options, relative_files) file_list = [] relative_files.each do |rel_file_name| - case type = File.stat(rel_file_name).ftype when "file" file_list << rel_file_name when "directory" next if options.exclude && options.exclude =~ rel_file_name - Find.find(rel_file_name) do |fn| - next if options.exclude && options.exclude =~ fn - next unless ParserFactory.can_parse(fn) - next unless File.file?(fn) - - file_list << fn.sub(%r{\./}, '') + dot_doc = File.join(rel_file_name, DOT_DOC_FILENAME) + if File.file?(dot_doc) + file_list.concat(parse_dot_doc_file(rel_file_name, dot_doc, options)) + else + file_list.concat(list_files_in_directory(rel_file_name, options)) end else raise RDocError.new("I can't deal with a #{type} #{rel_file_name}") @@ -137,6 +173,16 @@ module RDoc file_list end + # Return a list of the files to be processed in + # a directory. We know that this directory doesn't have + # a .document file, so we're looking for real files. However + # we may well contain subdirectories which must + # be tested for .document files + def list_files_in_directory(dir, options) + normalized_file_list(options, Dir.glob(File.join(dir, "*"))) + end + + # Parse each file on the command line, recursively entering # directories @@ -147,7 +193,7 @@ module RDoc files = options.files files = ["."] if files.empty? - file_list = normalized_file_list(options, *files) + file_list = normalized_file_list(options, files) file_list.each do |fn| $stderr.printf("\n%35s: ", File.basename(fn)) unless options.quiet @@ -155,8 +201,9 @@ module RDoc content = File.open(fn, "r") {|f| f.read} top_level = TopLevel.new(fn) - parser = ParserFactory.parser_for(top_level, fn, content, options) + parser = ParserFactory.parser_for(top_level, fn, content, options, @stats) file_info << parser.scan + @stats.num_files += 1 end file_info @@ -182,6 +229,8 @@ module RDoc TopLevel::reset + @stats = Stats.new + options = Options.instance options.parse(argv, GENERATORS) @@ -211,7 +260,11 @@ module RDoc ensure Dir.chdir(pwd) end + end + unless options.quiet + puts + @stats.print end end end diff --git a/lib/rdoc/ri/ri_descriptions.rb b/lib/rdoc/ri/ri_descriptions.rb index 9bd5c2d13b..96041f1c7e 100644 --- a/lib/rdoc/ri/ri_descriptions.rb +++ b/lib/rdoc/ri/ri_descriptions.rb @@ -100,6 +100,12 @@ module RI "Module" end + # the 'ClassDescription' subclass overrides this + # to format up the name of a parent + def superclass_string + nil + end + private def merge(into, from) @@ -116,6 +122,14 @@ module RI def display_name "Class" end + + def superclass_string + if @superclass && @superclass != "Object" + @superclass + else + nil + end + end end diff --git a/lib/rdoc/ri/ri_formatter.rb b/lib/rdoc/ri/ri_formatter.rb index f41a815435..8fd214437d 100644 --- a/lib/rdoc/ri/ri_formatter.rb +++ b/lib/rdoc/ri/ri_formatter.rb @@ -197,7 +197,6 @@ module RI end end - ###################################################################### def display_flow(flow) flow.each do |f| @@ -207,6 +206,7 @@ module RI end + ###################################################################### # Handle text with attributes. We're a base class: there are # different presentation classes (one, for example, uses overstrikes # to handle bold and underlinig, while another using ANSI escape @@ -278,27 +278,30 @@ module RI return unless txt && !txt.empty? txt = add_attributes_to(txt) + next_prefix = prefix.tr("^ ", " ") + linelen -= prefix.size line = [] until txt.empty? word = txt.next_word - if word.size + line.size > linelen - @indent.size - write_attribute_text(line) + if word.size + line.size > linelen + write_attribute_text(prefix, line) + prefix = next_prefix line = [] end line.concat(word) end - write_attribute_text(line) if line.length > 0 + write_attribute_text(prefix, line) if line.length > 0 end protected # overridden in specific formatters - def write_attribute_text(line) - print @indent + def write_attribute_text(prefix, line) + print prefix line.each do |achar| print achar.char end @@ -340,8 +343,8 @@ module RI BS = "\C-h" - def write_attribute_text(line) - print @indent + def write_attribute_text(prefix, line) + print prefix line.each do |achar| attr = achar.attr if (attr & (ITALIC+CODE)) != 0 @@ -371,15 +374,13 @@ module RI class AnsiFormatter < AttributeFormatter - BS = "\C-h" - def initialize(*args) print "\033[0m" super end - def write_attribute_text(line) - print @indent + def write_attribute_text(prefix, line) + print prefix curr_attr = 0 line.each do |achar| attr = achar.attr diff --git a/lib/rdoc/ri/ri_options.rb b/lib/rdoc/ri/ri_options.rb index 9b0704d421..fe323ed45f 100644 --- a/lib/rdoc/ri/ri_options.rb +++ b/lib/rdoc/ri/ri_options.rb @@ -16,6 +16,9 @@ module RI # can't find a pager attr_accessor :use_stdout + # should we just display a class list and exit + attr_reader :list_classes + # The width of the output line attr_reader :width @@ -28,6 +31,10 @@ module RI [ "--help", "-h", nil, "you're looking at it" ], + [ "--classes", "-c", nil, + "Display the names of classes and modules we\n" + + "know about"], + [ "--format", "-f", "<name>", "Format to use when displaying output:\n" + " " + RI::TextFormatter.list + "\n" + @@ -112,8 +119,8 @@ module RI EOT if short_form - class_list - puts "For help, type 'ri -h'" + puts "For help on options, type 'ri -h'" + puts "For a list of classes I know about, type 'ri -c'" else puts "Options:\n\n" OPTION_LIST.each do |long, short, arg, desc| @@ -136,30 +143,16 @@ module RI end end - def OptionList.class_list - paths = RI::Paths::PATH - if paths.empty? - puts "Before using ri, you need to generate documentation" - puts "using 'rdoc' with the --ri option" - else - @ri_reader = RI::RiReader.new(RI::RiCache.new(paths)) - puts - puts "Classes and modules I know about:" - puts - puts @ri_reader.class_names.sort.join(", ") - puts - end - end - end # Parse command line options. def parse - @use_stdout = !STDOUT.tty? - @width = 72 - @formatter = RI::TextFormatter.for("plain") + @use_stdout = !STDOUT.tty? + @width = 72 + @formatter = RI::TextFormatter.for("plain") + @list_classes = false begin @@ -170,6 +163,8 @@ module RI case opt when "--help" then OptionList.usage when "--no-pager" then @use_stdout = true + when "--classes" then @list_classes = true + when "--format" @formatter = RI::TextFormatter.for(arg) unless @formatter |