In Files

  • rdoc/rdoc.rb

Files

Class/Module Index [+]

Quicksearch

RDoc::RDoc

Encapsulate the production of rdoc documentation. Basically you can use this as you would invoke rdoc from the command line:

rdoc = RDoc::RDoc.new
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.

Constants

GENERATORS
Generator

This is the list of output generators that we support

Public Class Methods

extract_sections(flow, sections) click to toggle source

Given an array of flow items and an array of section names, extract those sections from the flow which have headings corresponding to a section name in the list. Return them in the order of names in the sections array.

 
               # File rdoc/usage.rb, line 165
def RDoc.extract_sections(flow, sections)
  result = []
  sections.each do |name|
    name = name.downcase
    copy_upto_level = nil

    flow.each do |item|
      case item
      when SM::Flow::H
        if copy_upto_level && item.level >= copy_upto_level
          copy_upto_level = nil
        else
          if item.text.downcase == name
            result << item
            copy_upto_level = item.level
          end
        end
      else
        if copy_upto_level
          result << item
        end
      end
    end
  end
  if result.empty?
    puts "Note to developer: requested section(s) [#{sections.join(', ')}] " +
         "not found"
    result = flow
  end
  result
end
find_comment(file) click to toggle source 
 
               # File rdoc/usage.rb, line 141
def RDoc.find_comment(file)
  catch(:exit) do
    # skip leading blank lines
    0 while (line = gets(file)) && (line =~ /^\s*$/)

    comment = []
    while line && line =~ /^\s*#/
      comment << line
      line = gets(file)
    end

    0 while line && (line = gets(file))
    return no_comment if comment.empty?
    return comment.join
  end
end
gets(file) click to toggle source

Find the first comment in the file (that isn't a shebang line) If the file doesn't start with a comment, report the fact and return empty string

 
               # File rdoc/usage.rb, line 133
def RDoc.gets(file)
  if (line = file.gets) && (line =~ /^#!/) # shebang
    throw :exit, find_comment(file)
  else
    line
  end
end
no_comment() click to toggle source

Report the fact that no doc comment count be found

 
               # File rdoc/usage.rb, line 199
def RDoc.no_comment
  $stderr.puts "No usage information available for this program"
  ""
end
usage(*args) click to toggle source

Display usage information from the comment at the top of the file. String arguments identify specific sections of the comment to display. An optional integer first argument specifies the exit status (defaults to 0)

 
               # File rdoc/usage.rb, line 81
def RDoc.usage(*args)
  exit_code = 0

  if args.size > 0
    status = args[0]
    if status.respond_to?(:to_int)
      exit_code = status.to_int
      args.shift
    end
  end

  # display the usage and exit with the given code
  usage_no_exit(*args)
  exit(exit_code)
end
usage_no_exit(*args) click to toggle source

Display usage

 
               # File rdoc/usage.rb, line 98
def RDoc.usage_no_exit(*args)
  main_program_file = caller[-1].sub(/:\d+$/, '')
  comment = File.open(main_program_file) do |file|
    find_comment(file)
  end

  comment = comment.gsub(/^\s*#/, '')

  markup = SM::SimpleMarkup.new
  flow_convertor = SM::ToFlow.new
  
  flow = markup.convert(comment, flow_convertor)

  format = "plain"

  unless args.empty?
    flow = extract_sections(flow, args)
  end

  options = RI::Options.instance
  if args = ENV["RI"]
    options.parse(args.split)
  end
  formatter = options.formatter.new(options, "")
  formatter.display_flow(flow)
end

Public Instance Methods

document(argv) click to toggle source

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

 
               # File rdoc/rdoc.rb, line 249
def document(argv)

  TopLevel::reset

  @stats = Stats.new

  options = Options.instance
  options.parse(argv, GENERATORS)

  @last_created = nil
  unless options.all_one_file
    @last_created = setup_output_dir(options.op_dir, options.force_update)
  end
  start_time = Time.now

  file_info = parse_files(options)

  if file_info.empty?
    $stderr.puts "\nNo newer files." unless options.quiet
  else
    gen = options.generator

    $stderr.puts "\nGenerating #{gen.key.upcase}..." unless options.quiet

    require gen.file_name

    gen_class = Generators.const_get(gen.class_name)
    gen = gen_class.for(options)

    pwd = Dir.pwd

    Dir.chdir(options.op_dir)  unless options.all_one_file

    begin
      Diagram.new(file_info, options).draw if options.diagram
      gen.generate(file_info)
      update_output_dir(".", start_time)
    ensure
      Dir.chdir(pwd)
    end
  end

  unless options.quiet
    puts
    @stats.print
  end
end