In Files

  • rdoc/generator.rb

Files

Class/Module Index [+]

Quicksearch

RDoc::Generator::Context

A Context is built by the parser to represent a container: contexts hold classes, modules, methods, require lists and include lists. ClassModule and TopLevel are the context objects we process here

Attributes

context[R]

Public Class Methods

build_class_list(classes, options, from, html_file, class_dir) click to toggle source
 
               # File rdoc/generator.rb, line 147
def self.build_class_list(classes, options, from, html_file, class_dir)
  classes << RDoc::Generator::Class.new(from, html_file, class_dir, options)

  from.each_classmodule do |mod|
    build_class_list(classes, options, mod, html_file, class_dir)
  end
end
            
build_indices(toplevels, options) click to toggle source

Generate:

  • a list of RDoc::Generator::File objects for each TopLevel object

  • a list of RDoc::Generator::Class objects for each first level class or module in the TopLevel objects

  • a complete list of all hyperlinkable terms (file, class, module, and method names)

 
               # File rdoc/generator.rb, line 130
def self.build_indices(toplevels, options)
  files = []
  classes = []

  toplevels.each do |toplevel|
    files << RDoc::Generator::File.new(toplevel, options,
                                       RDoc::Generator::FILE_DIR)
  end

  RDoc::TopLevel.all_classes_and_modules.each do |cls|
    build_class_list(classes, options, cls, files[0], 
                     RDoc::Generator::CLASS_DIR)
  end

  return files, classes
end
            
new(context, options) click to toggle source
 
               # File rdoc/generator.rb, line 155
def initialize(context, options)
  @context = context
  @options = options

  # HACK ugly
  @template = options.template_class
end
            

Public Instance Methods

add_table_of_sections() click to toggle source

create table of contents if we contain sections

 
               # File rdoc/generator.rb, line 462
def add_table_of_sections
  toc = []
  @context.sections.each do |section|
    if section.title then
      toc << {
        'secname' => section.title,
        'href'    => section.sequence
      }
    end
  end

  @values['toc'] = toc unless toc.empty?
end
            
aref_to(target) click to toggle source
 
               # File rdoc/generator.rb, line 429
def aref_to(target)
  if @options.all_one_file
    "#" + target
  else
    url(target)
  end
end
            
as_href(from_path) click to toggle source

Returns a reference to outselves to be used as an href= the form depends on whether we’re all in one file or in multiple files

 
               # File rdoc/generator.rb, line 179
def as_href(from_path)
  if @options.all_one_file
    "#" + path
  else
    RDoc::Markup::ToHtml.gen_relative_url from_path, path
  end
end
            
build_alias_summary_list(section) click to toggle source

Build a list of aliases for which we couldn’t find a corresponding method

 
               # File rdoc/generator.rb, line 227
def build_alias_summary_list(section)
  @context.aliases.map do |al|
    next unless al.section == section

    res = {
      'old_name' => al.old_name,
      'new_name' => al.new_name,
    }

    if al.comment and not al.comment.empty? then
      res['desc'] = markup al.comment, true
    end

    res
  end.compact
end
            
build_class_list(level, from, section, infile=nil) click to toggle source

Build the structured list of classes and modules contained in this context.

 
               # File rdoc/generator.rb, line 391
def build_class_list(level, from, section, infile=nil)
  prefix = '&nbsp;&nbsp;::' * level;
  res = ''

  from.modules.sort.each do |mod|
    next unless mod.section == section
    next if infile && !mod.defined_in?(infile)
    if mod.document_self
      res <<
        prefix <<
        'Module ' <<
        href(url(mod.viewer.path), 'link', mod.full_name) <<
        "<br />\n" <<
        build_class_list(level + 1, mod, section, infile)
    end
  end

  from.classes.sort.each do |cls|
    next unless cls.section == section
    next if infile and not cls.defined_in?(infile)

    if cls.document_self
      res <<
        prefix <<
        'Class ' <<
        href(url(cls.viewer.path), 'link', cls.full_name) <<
        "<br />\n" <<
        build_class_list(level + 1, cls, section, infile)
    end
  end

  res
end
            
build_constants_summary_list(section) click to toggle source

Build a list of constants

 
               # File rdoc/generator.rb, line 247
def build_constants_summary_list(section)
  @context.constants.map do |co|
    next unless co.section == section

    res = {
      'name'  => co.name,
      'value' => CGI.escapeHTML(co.value)
    }

    if co.comment and not co.comment.empty? then
      res['desc'] = markup co.comment, true
    end

    res
  end.compact
end
            
build_include_list(context) click to toggle source
 
               # File rdoc/generator.rb, line 268
def build_include_list(context)
  potentially_referenced_list(context.includes)
end
            
build_method_detail_list(section) click to toggle source

Build an array of arrays of method details. The outer array has up to six entries, public, private, and protected for both class methods, the other for instance methods. The inner arrays contain a hash for each method

 
               # File rdoc/generator.rb, line 320
def build_method_detail_list(section)
  outer = []

  methods = @methods.sort.select do |m|
    m.document_self and m.section == section
  end

  for singleton in [true, false]
    for vis in [ :public, :protected, :private ]
      res = []
      methods.each do |m|
        next unless m.visibility == vis and m.singleton == singleton

        row = {}

        if m.call_seq then
          row["callseq"] = m.call_seq.gsub(/->/, '&rarr;')
        else
          row["name"]        = CGI.escapeHTML(m.name)
          row["params"]      = m.params
        end

        desc = m.description.strip
        row["m_desc"]      = desc unless desc.empty?
        row["aref"]        = m.aref
        row["visibility"]  = m.visibility.to_s

        alias_names = []

        m.aliases.each do |other|
          if other.viewer then # won't be if the alias is private
            alias_names << {
              'name' => other.name,
              'aref'  => other.viewer.as_href(path)
            }
          end
        end

        row["aka"] = alias_names unless alias_names.empty?

        if @options.inline_source then
          code = m.source_code
          row["sourcecode"] = code if code
        else
          code = m.src_url
          if code then
            row["codeurl"] = code
            row["imgurl"]  = m.img_url
          end
        end

        res << row
      end

      if res.size > 0 then
        outer << {
          "type"     => vis.to_s.capitalize,
          "category" => singleton ? "Class" : "Instance",
          "methods"  => res
        }
      end
    end
  end

  outer
end
            
build_method_summary_list(path_prefix = "") click to toggle source

Build a summary list of all the methods in this context

 
               # File rdoc/generator.rb, line 212
def build_method_summary_list(path_prefix = "")
  collect_methods unless @methods

  @methods.sort.map do |meth|
    {
      "name" => CGI.escapeHTML(meth.name),
      "aref" => "##{meth.aref}"
    }
  end
end
            
build_requires_list(context) click to toggle source
 
               # File rdoc/generator.rb, line 264
def build_requires_list(context)
  potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] }
end
            
collect_methods() click to toggle source

Create a list of Method objects for each method in the corresponding context object. If the @options.show_all variable is set (corresponding to the --all option, we include all methods, otherwise just the public ones.

 
               # File rdoc/generator.rb, line 193
def collect_methods
  list = @context.method_list

  unless @options.show_all then
    list = list.select do |m|
      m.visibility == :public or
        m.visibility == :protected or
        m.force_documentation
    end
  end

  @methods = list.collect do |m|
    RDoc::Generator::Method.new m, self, @options
  end
end
            
diagram_reference(diagram) click to toggle source
 
               # File rdoc/generator.rb, line 441
def diagram_reference(diagram)
  res = diagram.gsub(/((?:src|href)=")(.*?)"/) {
    $1 + url($2) + '"'
  }
  res
end
            
document_self() click to toggle source
 
               # File rdoc/generator.rb, line 437
def document_self
  @context.document_self
end
            
find_symbol(symbol, method=nil) click to toggle source

Find a symbol in ourselves or our parent

 
               # File rdoc/generator.rb, line 451
def find_symbol(symbol, method=nil)
  res = @context.find_symbol(symbol, method)
  if res
    res = res.viewer
  end
  res
end
            
formatter() click to toggle source
 
               # File rdoc/generator.rb, line 163
def formatter
  @formatter ||= @options.formatter ||
    RDoc::Markup::ToHtmlCrossref.new(path, self, @options.show_hash)
end
            
href(link, cls, name) click to toggle source

convenience method to build a hyperlink

 
               # File rdoc/generator.rb, line 171
def href(link, cls, name)
  %Q{<a href="#{link}" class="#{cls}">#{name}</a>} #"
end
            
potentially_referenced_list(array) click to toggle source

Build a list from an array of Context items. Look up each in the AllReferences hash: if we find a corresponding entry, we generate a hyperlink to it, otherwise just output the name. However, some names potentially need massaging. For example, you may require a Ruby file without the .rb extension, but the file names we know about may have it. To deal with this, we pass in a block which performs the massaging, returning an array of alternative names to match

 
               # File rdoc/generator.rb, line 281
    def potentially_referenced_list(array)
      res = []
      array.each do |i|
        ref = AllReferences[i.name]
#         if !ref
#           container = @context.parent
#           while !ref && container
#             name = container.name + "::" + i.name
#             ref = AllReferences[name]
#             container = container.parent
#           end
#         end

        ref = @context.find_symbol(i.name)
        ref = ref.viewer if ref

        if !ref && block_given?
          possibles = yield(i.name)
          while !ref and !possibles.empty?
            ref = AllReferences[possibles.shift]
          end
        end
        h_name = CGI.escapeHTML(i.name)
        if ref and ref.document_self
          path = url(ref.path)
          res << { "name" => h_name, "aref" => path }
        else
          res << { "name" => h_name }
        end
      end
      res
    end
            
url(target) click to toggle source
 
               # File rdoc/generator.rb, line 425
def url(target)
  RDoc::Markup::ToHtml.gen_relative_url path, target
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus