# File lib/rdoc/rdoc.rb, line 334
  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\nhas proper syntax:\n\n\#{Gem.ruby} -c \#{filename}\n\nRDoc is not a full Ruby parser and will fail when fed invalid ruby programs.\n\nThe internal error was:\n\n\\t(\#{e.class}) \#{e.message}\n\n"

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

    raise e
    nil
  end