From b0f13cfebec316491909e312608834c87792ca9f Mon Sep 17 00:00:00 2001 From: drbrain Date: Mon, 7 Jan 2008 00:42:03 +0000 Subject: Clean up comments and whitespace in RDoc generators git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@14919 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/rdoc/generators/chm_generator.rb | 55 +++--- lib/rdoc/generators/html_generator.rb | 357 ++++++++++++++++++---------------- lib/rdoc/generators/ri_generator.rb | 82 +++----- lib/rdoc/generators/xml_generator.rb | 16 +- 4 files changed, 248 insertions(+), 262 deletions(-) (limited to 'lib') diff --git a/lib/rdoc/generators/chm_generator.rb b/lib/rdoc/generators/chm_generator.rb index 51eeda8dd1..354a444689 100644 --- a/lib/rdoc/generators/chm_generator.rb +++ b/lib/rdoc/generators/chm_generator.rb @@ -6,12 +6,13 @@ module Generators HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe" + ## # Standard generator factory + def CHMGenerator.for(options) CHMGenerator.new(options) end - def initialize(*args) super @op_name = @options.op_name || "rdoc" @@ -22,32 +23,35 @@ module Generators stat = File.stat(HHC_PATH) rescue $stderr << - "\n.chm output generation requires that Microsoft's Html Help\n" << - "Workshop is installed. RDoc looks for it in:\n\n " << - HHC_PATH << - "\n\nYou can download a copy for free from:\n\n" << - " http://msdn.microsoft.com/library/default.asp?" << - "url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n" - + "\n.chm output generation requires that Microsoft's Html Help\n" << + "Workshop is installed. RDoc looks for it in:\n\n " << + HHC_PATH << + "\n\nYou can download a copy for free from:\n\n" << + " http://msdn.microsoft.com/library/default.asp?" << + "url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n" + exit 99 end - # Generate the html as normal, then wrap it - # in a help project + ## + # Generate the html as normal, then wrap it in a help project + def generate(info) super @project_name = @op_name + ".hhp" create_help_project end - # The project contains the project file, a table of contents - # and an index + ## + # The project contains the project file, a table of contents and an index + def create_help_project create_project_file create_contents_and_index compile_project end + ## # The project file links together all the various # files that go to make up the help. @@ -56,16 +60,17 @@ module Generators values = { "title" => @options.title, "opname" => @op_name } files = [] @files.each do |f| - files << { "html_file_name" => f.path } + files << { "html_file_name" => f.path } end values['all_html_files'] = files - + File.open(@project_name, "w") do |f| template.write_html_on(f, values) end end + ## # The contents is a list of all files and modules. # For each we include as sub-entries the list # of methods they contain. As we build the contents @@ -76,37 +81,39 @@ module Generators index = [] (@files+@classes).sort.each do |entry| - content_entry = { "c_name" => entry.name, "ref" => entry.path } - index << { "name" => entry.name, "aref" => entry.path } + content_entry = { "c_name" => entry.name, "ref" => entry.path } + index << { "name" => entry.name, "aref" => entry.path } - internals = [] + internals = [] - methods = entry.build_method_summary_list(entry.path) + methods = entry.build_method_summary_list(entry.path) - content_entry["methods"] = methods unless methods.empty? + content_entry["methods"] = methods unless methods.empty? contents << content_entry - index.concat methods + index.concat methods end values = { "contents" => contents } template = TemplatePage.new(RDoc::Page::CONTENTS) File.open("contents.hhc", "w") do |f| - template.write_html_on(f, values) + template.write_html_on(f, values) end values = { "index" => index } template = TemplatePage.new(RDoc::Page::CHM_INDEX) File.open("index.hhk", "w") do |f| - template.write_html_on(f, values) - end + template.write_html_on(f, values) + end end + ## # Invoke the windows help compiler to compiler the project + def compile_project system(HHC_PATH, @project_name) end end - end + diff --git a/lib/rdoc/generators/html_generator.rb b/lib/rdoc/generators/html_generator.rb index 4348703c30..1497ed7483 100644 --- a/lib/rdoc/generators/html_generator.rb +++ b/lib/rdoc/generators/html_generator.rb @@ -1,39 +1,3 @@ -# We're responsible for generating all the HTML files -# from the object tree defined in code_objects.rb. We -# generate: -# -# [files] an html file for each input file given. These -# input files appear as objects of class -# TopLevel -# -# [classes] an html file for each class or module encountered. -# These classes are not grouped by file: if a file -# contains four classes, we'll generate an html -# file for the file itself, and four html files -# for the individual classes. -# -# [indices] we generate three indices for files, classes, -# and methods. These are displayed in a browser -# like window with three index panes across the -# top and the selected description below -# -# Method descriptions appear in whatever entity (file, class, -# or module) that contains them. -# -# We generate files in a structure below a specified subdirectory, -# normally +doc+. -# -# opdir -# | -# |___ files -# | |__ per file summaries -# | -# |___ classes -# |__ per class/module descriptions -# -# HTML is generated using the Template class. -# - require 'fileutils' require 'rdoc/options' @@ -44,24 +8,32 @@ require 'cgi' module Generators - # Name of sub-direcories that hold file and class/module descriptions + ## + # Name of sub-direcory that holds file descriptions FILE_DIR = "files" + + ## + # Name of sub-direcory that holds class descriptions + CLASS_DIR = "classes" + + ## + # Name of the RDoc CSS file + CSS_NAME = "rdoc-style.css" - ## # Build a hash of all items that can be cross-referenced. - # This is used when we output required and included names: + # This is used when we output required and included names: # if the names appear in this hash, we can generate # an html cross reference to the appropriate description. - # We also use this when parsing comment blocks: any decorated + # We also use this when parsing comment blocks: any decorated # words matching an entry in this list are hyperlinked. class AllReferences @@refs = {} - + def AllReferences::reset @@refs = {} end @@ -79,7 +51,6 @@ module Generators end end - ## # Subclass of the SM::ToHtml class that supports looking # up words in the AllReferences list. Those that are @@ -87,6 +58,8 @@ module Generators # be hyperlinked class HyperlinkHtml < SM::ToHtml + + ## # We need to record the html path of our caller so we can generate # correct relative paths for any hyperlinks that we find def initialize(from_path, context) @@ -98,6 +71,7 @@ module Generators @context = context end + ## # We're invoked when any text matches the CROSSREF pattern # (defined in MarkUp). If we fine the corresponding reference, # generate a hyperlink. If the name we're looking for contains @@ -134,9 +108,10 @@ module Generators end end - + ## # Generate a hyperlink for url, labeled with text. Handle the # special cases for img: and link: described under handle_special_HYPEDLINK + def gen_url(url, text) if url =~ /([A-Za-z]+):(.*)/ type = $1 @@ -155,7 +130,7 @@ module Generators end end - if (type == "http" || type == "link") && + if (type == "http" || type == "link") && url =~ /\.(gif|png|jpg|jpeg|bmp)$/ "" @@ -164,6 +139,7 @@ module Generators end end + ## # And we're invoked with a potential external hyperlink mailto: # just gets inserted. http: links are checked to see if they # reference an image. If so, that image gets inserted using an @@ -176,14 +152,14 @@ module Generators gen_url(url, url) end - # HEre's a hypedlink where the label is different to the URL + ## + # Here's a hypedlink where the label is different to the URL #