diff options
Diffstat (limited to 'lib/rdoc/rdoc.rb')
-rw-r--r-- | lib/rdoc/rdoc.rb | 165 |
1 files changed, 84 insertions, 81 deletions
diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb index ca8c5d02a2..b1359511bf 100644 --- a/lib/rdoc/rdoc.rb +++ b/lib/rdoc/rdoc.rb @@ -1,15 +1,8 @@ -# See README. -# - - -VERSION_STRING = %{RDoc V1.0.1 - 20041108} - - require 'rdoc/parsers/parse_rb.rb' require 'rdoc/parsers/parse_c.rb' require 'rdoc/parsers/parse_f95.rb' - require 'rdoc/parsers/parse_simple.rb' + require 'rdoc/options' require 'rdoc/diagram' @@ -18,19 +11,25 @@ require 'find' require 'fileutils' require 'time' -# We put rdoc stuff in the RDoc module to avoid namespace clutter. -# -# ToDo: This isn't universally true. -# +## # :include: README module RDoc - # Name of the dotfile that contains the description of files to be - # processed in the current directory + ## + # RDoc version you are using + + VERSION = "2.0.0" + + ## + # 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 @@ -46,13 +45,14 @@ module RDoc end end + ## + # Exception thrown by any rdoc error. - # Exception thrown by any rdoc error. Only the #message part is - # of use externally. + class Error < StandardError; end - class RDocError < Exception - end + RDocError = Error # :nodoc: + ## # Encapsulate the production of rdoc documentation. Basically # you can use this as you would invoke rdoc from the command # line: @@ -61,24 +61,25 @@ module RDoc # rdoc.document(args) # # where _args_ is an array of strings, each corresponding to - # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb + # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb # for details. - + class RDoc + Generator = Struct.new(:file_name, :class_name, :key) + ## # This is the list of output generators that we # support - - Generator = Struct.new(:file_name, :class_name, :key) - + GENERATORS = {} - $:.collect {|d| - File::expand_path(d) - }.find_all {|d| - File::directory?("#{d}/rdoc/generators") - }.each {|dir| - Dir::entries("#{dir}/rdoc/generators").each {|gen| + + $LOAD_PATH.collect do |d| + File.expand_path d + end.find_all do |d| + File.directory? "#{d}/rdoc/generators" + end.each do |dir| + Dir.entries("#{dir}/rdoc/generators").each do |gen| next unless /(\w+)_generator.rb$/ =~ gen type = $1 unless GENERATORS.has_key? type @@ -86,31 +87,28 @@ module RDoc "#{type.upcase}Generator".intern, type) end - } - } + end + end - ####### private - ####### ## # Report an error message and exit - + def error(msg) - raise RDocError.new(msg) + raise RDoc::Error, msg end - + ## - # Create an output dir if it doesn't exist. If it does - # exist, but doesn't contain the flag file <tt>created.rid</tt> - # then we refuse to use it, as we may clobber some - # manually generated documentation - + # Create an output dir if it doesn't exist. If it does exist, but doesn't + # contain the flag file <tt>created.rid</tt> then we refuse to use it, as + # we may clobber some manually generated documentation + def setup_output_dir(op_dir, force) flag_file = output_flag_file(op_dir) if File.exist?(op_dir) unless File.directory?(op_dir) - error "'#{op_dir}' exists, and is not a directory" + error "'#{op_dir}' exists, and is not a directory" end begin created = File.read(flag_file) @@ -129,19 +127,25 @@ module RDoc last end + ## # Update the flag file in an output directory. + def update_output_dir(op_dir, time) File.open(output_flag_file(op_dir), "w") {|f| f.puts time.rfc2822 } end + ## # Return the path name of the flag file in an output directory. + def output_flag_file(op_dir) File.join(op_dir, "created.rid") end - # The .document file contains a list of file and directory name - # patterns, representing candidates for documentation. It may - # also contain comments (starting with '#') + ## + # 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(/#.*/, '') @@ -155,20 +159,20 @@ module RDoc result end - - # Given a list of files and directories, create a list - # of all the Ruby files they contain. - # - # If +force_doc+ is true, we always add the given files. - # If false, only add files that we guarantee we can parse - # It is true when looking at files given on the command line, - # false when recursing through subdirectories. + ## + # Given a list of files and directories, create a list of all the Ruby + # files they contain. # - # The effect of this is that if you want a file with a non- - # standard extension parsed, you must name it explicity. + # If +force_doc+ is true we always add the given files, if false, only + # add files that we guarantee we can parse. It is true when looking at + # files given on the command line, false when recursing through + # subdirectories. # + # The effect of this is that if you want a file with a non-standard + # extension parsed, you must name it explicity. - def normalized_file_list(options, relative_files, force_doc = false, exclude_pattern=nil) + def normalized_file_list(options, relative_files, force_doc = false, + exclude_pattern = nil) file_list = [] relative_files.each do |rel_file_name| @@ -187,27 +191,27 @@ module RDoc 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}") + raise RDoc::Error, "I can't deal with a #{type} #{rel_file_name}" end end + 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 + ## + # 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, "*")), false, options.exclude) end - - # Parse each file on the command line, recursively entering - # directories + ## + # Parse each file on the command line, recursively entering directories. def parse_files(options) - file_info = [] files = options.files @@ -217,7 +221,7 @@ module RDoc file_list.each do |fn| $stderr.printf("\n%35s: ", File.basename(fn)) unless options.quiet - + content = File.open(fn, "r:ascii-8bit") {|f| f.read} if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/] if enc = Encoding.find($1) @@ -234,32 +238,30 @@ module RDoc file_info end - public - ################################################################### - # + ## # Format up one or more files according to the given arguments. - # For simplicity, _argv_ is an array of strings, equivalent to the - # strings that would be passed on the command line. (This isn't a - # coincidence, as we _do_ pass in ARGV when running - # interactively). For a list of options, see rdoc/rdoc.rb. By - # default, output will be stored in a directory called +doc+ below - # the current directory, so make sure you're somewhere writable - # before invoking. # - # Throws: RDocError on error + # For simplicity, _argv_ is an array of strings, equivalent to the strings + # that would be passed on the command line. (This isn't a coincidence, as + # we _do_ pass in ARGV when running interactively). For a list of options, + # see rdoc/rdoc.rb. By default, output will be stored in a directory + # called +doc+ below the current directory, so make sure you're somewhere + # writable before invoking. + # + # Throws: RDoc::Error on error def document(argv) - TopLevel::reset @stats = Stats.new - options = Options.instance - options.parse(argv, GENERATORS) + options = Options.new GENERATORS + options.parse argv @last_created = nil + unless options.all_one_file @last_created = setup_output_dir(options.op_dir, options.force_update) end @@ -298,5 +300,6 @@ module RDoc end end end + end |