Extended maintenance of Ruby versions 1.8.7 and 1.9.2 ended on July 31, 2014. Read more

In Files

  • rdoc/generators/html_generator.rb

Files

Class/Module Index [+]

Quicksearch

Generators::ContextUser

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

new(context, options) click to toggle source
 
               # File rdoc/generators/html_generator.rb, line 294
def initialize(context, options)
  @context = context
  @options = options
end
            

Public Instance Methods

add_table_of_sections() click to toggle source

create table of contents if we contain sections

 
               # File rdoc/generators/html_generator.rb, line 565
def add_table_of_sections
  toc = []
  @context.sections.each do |section|
    if section.title
      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/generators/html_generator.rb, line 534
def aref_to(target)
  if @options.all_one_file
    "#" + target
  else
    url(target)
  end
end
            
as_href(from_path) click to toggle source

return 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/generators/html_generator.rb, line 308
def as_href(from_path)
  if @options.all_one_file
    "#" + path
  else
    HTMLGenerator.gen_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/generators/html_generator.rb, line 346
def build_alias_summary_list(section)
  values = []
  @context.aliases.each do |al|
    next unless al.section == section
    res = {
      'old_name' => al.old_name,
      'new_name' => al.new_name,
    }
    if al.comment && !al.comment.empty?
      res['desc'] = markup(al.comment, true)
    end
    values << res
  end
  values
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/generators/html_generator.rb, line 497
def build_class_list(level, from, section, infile=nil)
  res = ""
  prefix = "&nbsp;&nbsp;::" * level;

  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 && !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/generators/html_generator.rb, line 363
def build_constants_summary_list(section)
  values = []
  @context.constants.each do |co|
    next unless co.section == section
    res = {
      'name'  => co.name,
      'value' => CGI.escapeHTML(co.value)
    }
    res['desc'] = markup(co.comment, true) if co.comment && !co.comment.empty?
    values << res
  end
  values
end
            
build_include_list(context) click to toggle source
 
               # File rdoc/generators/html_generator.rb, line 381
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/generators/html_generator.rb, line 432
def build_method_detail_list(section)
  outer = []

  methods = @methods.sort
  for singleton in [true, false]
    for vis in [ :public, :protected, :private ] 
      res = []
      methods.each do |m|
        if m.section == section and
            m.document_self and 
            m.visibility == vis and 
            m.singleton == singleton
          row = {}
          if m.call_seq
            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   # won't be if the alias is private
              alias_names << {
                'name' => other.name,
                'aref'  => other.viewer.as_href(path)
              } 
            end
          end
          unless alias_names.empty?
            row["aka"] = alias_names
          end

          if @options.inline_source
            code = m.source_code
            row["sourcecode"] = code if code
          else
            code = m.src_url
            if code
              row["codeurl"] = code
              row["imgurl"]  = m.img_url
            end
          end
          res << row
        end
      end
      if res.size > 0 
        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/generators/html_generator.rb, line 330
def build_method_summary_list(path_prefix="")
  collect_methods unless @methods
  meths = @methods.sort
  res = []
  meths.each do |meth|
    res << {
      "name" => CGI.escapeHTML(meth.name),
      "aref" => "#{path_prefix}\##{meth.aref}" 
    }
  end
  res
end
            
build_requires_list(context) click to toggle source
 
               # File rdoc/generators/html_generator.rb, line 377
def build_requires_list(context)
  potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] }
end
            
collect_methods() click to toggle source

Create a list of HtmlMethod 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/generators/html_generator.rb, line 321
def collect_methods
  list = @context.method_list
  unless @options.show_all
    list = list.find_all {|m| m.visibility == :public || m.visibility == :protected || m.force_documentation }
  end
  @methods = list.collect {|m| HtmlMethod.new(m, self, @options) }
end
            
diagram_reference(diagram) click to toggle source
 
               # File rdoc/generators/html_generator.rb, line 546
def diagram_reference(diagram)
  res = diagram.gsub(/((?:src|href)=")(.*?)"/) {
    $1 + url($2) + '"'
  }
  res
end
            
document_self() click to toggle source
 
               # File rdoc/generators/html_generator.rb, line 542
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/generators/html_generator.rb, line 555
def find_symbol(symbol, method=nil)
  res = @context.find_symbol(symbol, method)
  if res
    res = res.viewer
  end
  res
end
            
href(link, cls, name) click to toggle source

convenience method to build a hyperlink

 
               # File rdoc/generators/html_generator.rb, line 300
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 Htmlxxx 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/generators/html_generator.rb, line 394
    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/generators/html_generator.rb, line 530
def url(target)
  HTMLGenerator.gen_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