RDoc

# File lib/rdoc/rdoc.rb, line 427
def document options
  RDoc::RDoc.reset
  RDoc::RDoc.current = self

  if RDoc::Options === options then
    @options = options
    @options.finish
  else
    @options = load_options
    @options.parse options
  end

  if @options.pipe then
    handle_pipe
    exit
  end

  @exclude = @options.exclude

  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.default_title = "RDoc Documentation"

  RDoc::TopLevel.complete @options.visibility

  @stats.coverage_level = @options.coverage_report

  if @options.coverage_report then
    puts

    puts @stats.report
  elsif file_info.empty? then
    $stderr.puts "\nNo newer files." unless @options.quiet
  else
    gen_klass = @options.generator

    @generator = gen_klass.new @options

    generate file_info
  end

  if @stats and (@options.coverage_report or not @options.quiet) then
    puts
    puts @stats.summary
  end

  exit @stats.fully_documented? if @options.coverage_report
end

# File lib/rdoc/rdoc.rb, line 109
def error(msg)
  raise RDoc::Error, msg
end

# File lib/rdoc/rdoc.rb, line 117
def gather_files files
  files = ["."] if files.empty?

  file_list = normalized_file_list files, true, @exclude

  file_list = file_list.uniq

  file_list = remove_unparseable file_list
end

# File lib/rdoc/rdoc.rb, line 487
def generate file_info
  Dir.chdir @options.op_dir do
    unless @options.quiet then
      $stderr.puts "\nGenerating #{@generator.class.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
    end

    @generator.generate file_info
    update_output_dir '.', @start_time, @last_modified
  end
end

# File lib/rdoc/rdoc.rb, line 130
def handle_pipe
  @html = RDoc::Markup::ToHtml.new

  parser = RDoc::Text::MARKUP_FORMAT[@options.markup]

  document = parser.parse $stdin.read

  out = @html.convert document

  $stdout.write out
end

# File lib/rdoc/rdoc.rb, line 145
def install_siginfo_handler
  return unless Signal.list.include? 'INFO'

  @old_siginfo = trap 'INFO' do
    puts @current if @current
  end
end

# File lib/rdoc/rdoc.rb, line 319
def list_files_in_directory dir
  files = Dir.glob File.join(dir, "*")

  normalized_file_list files, false, @options.exclude
end

# File lib/rdoc/rdoc.rb, line 157
def load_options
  options_file = File.expand_path '.rdoc_options'
  return RDoc::Options.new unless File.exist? options_file

  RDoc.load_yaml

  parse_error = if Object.const_defined? :Psych then
                  Psych::SyntaxError
                else
                  ArgumentError
                end

  begin
    options = YAML.load_file '.rdoc_options'
  rescue *parse_error
  end

  raise RDoc::Error, "#{options_file} is not a valid rdoc options file" unless
    RDoc::Options === options

  options
end

# File lib/rdoc/rdoc.rb, line 278
def normalized_file_list(relative_files, force_doc = false,
                         exclude_pattern = nil)
  file_list = []

  relative_files.each do |rel_file_name|
    next if exclude_pattern && exclude_pattern =~ rel_file_name
    stat = File.stat rel_file_name rescue next

    case type = stat.ftype
    when "file" then
      next if last_modified = @last_modified[rel_file_name] and
              stat.mtime.to_i <= last_modified.to_i

      if force_doc or RDoc::Parser.can_parse(rel_file_name) then
        file_list << rel_file_name.sub(%r^\.\//, '')
        @last_modified[rel_file_name] = stat.mtime
      end
    when "directory" then
      next if rel_file_name == "CVS" || rel_file_name == ".svn"

      dot_doc = File.join rel_file_name, RDoc::DOT_DOC_FILENAME

      if File.file? dot_doc then
        file_list << parse_dot_doc_file(rel_file_name, dot_doc)
      else
        file_list << list_files_in_directory(rel_file_name)
      end
    else
      raise RDoc::Error, "I can't deal with a #{type} #{rel_file_name}"
    end
  end

  file_list.flatten
end

# File lib/rdoc/rdoc.rb, line 243
def output_flag_file(op_dir)
  File.join op_dir, "created.rid"
end

# File lib/rdoc/rdoc.rb, line 252
def parse_dot_doc_file in_dir, filename
  # read and strip comments
  patterns = File.read(filename).gsub(%r#.*/, '')

  result = []

  patterns.split.each do |patt|
    candidates = Dir.glob(File.join(in_dir, patt))
    result.concat normalized_file_list(candidates)
  end

  result
end

# File lib/rdoc/rdoc.rb, line 328
  def parse_file filename
    if defined?(Encoding) then
      encoding = @options.encoding
      filename = filename.encode encoding
    end

    @stats.add_file filename

    content = RDoc::Encoding.read_file filename, encoding

    return unless content

    top_level = RDoc::TopLevel.new filename

    parser = RDoc::Parser.for top_level, filename, content, @options, @stats

    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 "Before reporting this, could you check that the file you're documenting
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:

\t(#{e.class}) #{e.message}

"

    $stderr.puts e.backtrace.join("\n\t") if $DEBUG_RDOC

    raise e
    nil
  end

# File lib/rdoc/rdoc.rb, line 379
def parse_files files
  file_list = gather_files files
  @stats = RDoc::Stats.new file_list.size, @options.verbosity

  return [] if file_list.empty?

  file_info = []

  @stats.begin_adding

  file_info = file_list.map do |filename|
    @current = filename
    parse_file filename
  end.compact

  @stats.done_adding

  file_info
end

# File lib/rdoc/rdoc.rb, line 501
def remove_siginfo_handler
  return unless Signal.list.key? 'INFO'

  handler = @old_siginfo || 'DEFAULT'

  trap 'INFO', handler
end

# File lib/rdoc/rdoc.rb, line 403
def remove_unparseable files
  files.reject do |file|
    file =~ %r\.(?:class|eps|erb|scpt\.txt|ttf|yml)$/ or
      (file =~ %rtags$/ and
       open(file, 'rb') { |io|
         io.read(100) =~ %r\A(\f\n[^,]+,\d+$|!_TAG_)/
       })
  end
end

# File lib/rdoc/rdoc.rb, line 185
  def setup_output_dir(dir, force)
    flag_file = output_flag_file dir

    last = {}

    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
        open flag_file do |io|
          unless force then
            Time.parse io.gets

            io.each do |line|
              file, time = line.split "\t", 2
              time = Time.parse(time) rescue next
              last[file] = time
            end
          end
        end
      rescue SystemCallError, TypeError
        error "
Directory #{dir} already exists, but it looks like it isn't an RDoc directory.

Because RDoc doesn't want to risk destroying any of your existing files,
you'll need to specify a different output directory name (using the --op <dir>
option)

"
      end unless @options.force_output
    else
      FileUtils.mkdir_p dir
      FileUtils.touch output_flag_file dir
    end

    last
  end

# File lib/rdoc/rdoc.rb, line 229
def update_output_dir(op_dir, time, last = {})
  return if @options.dry_run or not @options.update_output_dir

  open output_flag_file(op_dir), "w" do |f|
    f.puts time.rfc2822
    last.each do |n, t|
      f.puts "#{n}\t#{t.rfc2822}"
    end
  end
end