diff options
Diffstat (limited to 'lib/rdoc/rdoc.rb')
-rw-r--r-- | lib/rdoc/rdoc.rb | 104 |
1 files changed, 68 insertions, 36 deletions
diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb index 8771b408d9..a885d8dded 100644 --- a/lib/rdoc/rdoc.rb +++ b/lib/rdoc/rdoc.rb @@ -1,5 +1,6 @@ require 'rdoc' +require 'rdoc/encoding' require 'rdoc/parser' # Simple must come first @@ -23,7 +24,28 @@ require 'time' # 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 for details. +# give rdoc on the command line. See <tt>rdoc --help<tt> for details. +# +# = Plugins +# +# When you <tt>require 'rdoc/rdoc'</tt> RDoc looks for 'rdoc/discover' files +# in your installed gems. This can be used to load alternate generators or +# add additional preprocessor directives. +# +# You will want to wrap your plugin loading in an RDoc version check. +# Something like: +# +# begin +# gem 'rdoc', '~> 3' +# require 'path/to/my/awesome/rdoc/plugin' +# rescue Gem::LoadError +# end +# +# The most obvious plugin type is a new output generator. See RDoc::Generator +# for details. +# +# You can also hook into RDoc::Markup to add new directives (:nodoc: is a +# directive). See RDoc::Markup::PreProcess::register for details. class RDoc::RDoc @@ -79,6 +101,10 @@ class RDoc::RDoc @current = rdoc end + ## + # Creates a new RDoc::RDoc instance. Call #document to parse files and + # generate documentation. + def initialize @current = nil @exclude = nil @@ -142,7 +168,9 @@ class RDoc::RDoc last = {} - if File.exist? dir then + if @options.dry_run then + # do nothing + elsif File.exist? dir then error "#{dir} exists and is not a directory" unless File.directory? dir begin @@ -167,7 +195,7 @@ you'll need to specify a different output directory name (using the --op <dir> option) ERROR - end + end unless @options.force_output else FileUtils.mkdir_p dir end @@ -179,6 +207,8 @@ option) # Update the flag file in an output directory. def update_output_dir(op_dir, time, last = {}) + return if @options.dry_run + open output_flag_file(op_dir), "w" do |f| f.puts time.rfc2822 last.each do |n, t| @@ -277,7 +307,9 @@ option) def parse_file filename @stats.add_file filename - content = read_file_contents filename + encoding = @options.encoding if defined?(Encoding) + + content = RDoc::Encoding.read_file filename, encoding return unless content @@ -288,11 +320,22 @@ option) return unless parser parser.scan + + # restart documentation for the classes & modules found + top_level.classes_or_modules.each do |cm| + cm.done_documenting = false + end + + top_level + rescue => e $stderr.puts <<-EOF Before reporting this, could you check that the file you're documenting -compiles cleanly--RDoc is not a full Ruby parser, and gets confused easily if -fed invalid programs. +has proper syntax: + + #{Gem.ruby} -c #{filename} + +RDoc is not a full Ruby parser and will fail when fed invalid ruby programs. The internal error was: @@ -300,7 +343,7 @@ The internal error was: EOF - $stderr.puts e.backtrace.join("\n\t") if $RDOC_DEBUG + $stderr.puts e.backtrace.join("\n\t") if $DEBUG_RDOC raise e nil @@ -344,11 +387,9 @@ The internal error was: # 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 + # see <tt>rdoc --help</tt>. 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) RDoc::TopLevel.reset @@ -364,29 +405,36 @@ The internal error was: @exclude = @options.exclude - @last_modified = setup_output_dir @options.op_dir, @options.force_update + unless @options.coverage_report then + @last_modified = setup_output_dir @options.op_dir, @options.force_update + end start_time = Time.now file_info = parse_files @options.files - @options.title = "RDoc Documentation" + @options.default_title = "RDoc Documentation" + + RDoc::TopLevel.complete @options.visibility - if file_info.empty? + if @options.coverage_report then + puts + puts @stats.report + elsif file_info.empty? $stderr.puts "\nNo newer files." unless @options.quiet else gen_klass = @options.generator - unless @options.quiet then - $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')}..." - end - - @generator = gen_klass.for @options + @generator = gen_klass.new @options Dir.chdir @options.op_dir do begin self.class.current = self + unless @options.quiet then + $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')} format into #{Dir.pwd}..." + end + @generator.generate file_info update_output_dir ".", start_time, @last_modified ensure @@ -397,26 +445,10 @@ The internal error was: unless @options.quiet or not @stats then puts - @stats.print - end - end - - def read_file_contents(filename) - content = open filename, "rb" do |f| f.read end - - utf8 = content.sub!(/\A\xef\xbb\xbf/, '') - if defined? Encoding then - if /coding[=:]\s*([^\s;]+)/i =~ content[%r"\A(?:#!.*\n)?.*\n"] - enc = ::Encoding.find($1) - end - if enc ||= (Encoding::UTF_8 if utf8) - content.force_encoding(enc) - end + puts @stats.summary end - content - rescue Errno::EISDIR, Errno::ENOENT - nil + exit @stats.fully_documented? if @options.coverage_report end ## |