1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

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
This commit is contained in:
drbrain 2008-01-07 00:42:03 +00:00
parent ee6abe3252
commit b0f13cfebe
4 changed files with 248 additions and 262 deletions

View file

@ -6,12 +6,13 @@ module Generators
HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe" HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
##
# Standard generator factory # Standard generator factory
def CHMGenerator.for(options) def CHMGenerator.for(options)
CHMGenerator.new(options) CHMGenerator.new(options)
end end
def initialize(*args) def initialize(*args)
super super
@op_name = @options.op_name || "rdoc" @op_name = @options.op_name || "rdoc"
@ -32,22 +33,25 @@ module Generators
exit 99 exit 99
end 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) def generate(info)
super super
@project_name = @op_name + ".hhp" @project_name = @op_name + ".hhp"
create_help_project create_help_project
end 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 def create_help_project
create_project_file create_project_file
create_contents_and_index create_contents_and_index
compile_project compile_project
end end
##
# The project file links together all the various # The project file links together all the various
# files that go to make up the help. # files that go to make up the help.
@ -66,6 +70,7 @@ module Generators
end end
end end
##
# The contents is a list of all files and modules. # The contents is a list of all files and modules.
# For each we include as sub-entries the list # For each we include as sub-entries the list
# of methods they contain. As we build the contents # of methods they contain. As we build the contents
@ -101,12 +106,14 @@ module Generators
end end
end end
##
# Invoke the windows help compiler to compiler the project # Invoke the windows help compiler to compiler the project
def compile_project def compile_project
system(HHC_PATH, @project_name) system(HHC_PATH, @project_name)
end end
end end
end end

View file

@ -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 'fileutils'
require 'rdoc/options' require 'rdoc/options'
@ -44,12 +8,20 @@ require 'cgi'
module Generators module Generators
# Name of sub-direcories that hold file and class/module descriptions ##
# Name of sub-direcory that holds file descriptions
FILE_DIR = "files" FILE_DIR = "files"
CLASS_DIR = "classes"
CSS_NAME = "rdoc-style.css"
##
# 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. # Build a hash of all items that can be cross-referenced.
@ -79,7 +51,6 @@ module Generators
end end
end end
## ##
# Subclass of the SM::ToHtml class that supports looking # Subclass of the SM::ToHtml class that supports looking
# up words in the AllReferences list. Those that are # up words in the AllReferences list. Those that are
@ -87,6 +58,8 @@ module Generators
# be hyperlinked # be hyperlinked
class HyperlinkHtml < SM::ToHtml class HyperlinkHtml < SM::ToHtml
##
# We need to record the html path of our caller so we can generate # We need to record the html path of our caller so we can generate
# correct relative paths for any hyperlinks that we find # correct relative paths for any hyperlinks that we find
def initialize(from_path, context) def initialize(from_path, context)
@ -98,6 +71,7 @@ module Generators
@context = context @context = context
end end
##
# We're invoked when any text matches the CROSSREF pattern # We're invoked when any text matches the CROSSREF pattern
# (defined in MarkUp). If we fine the corresponding reference, # (defined in MarkUp). If we fine the corresponding reference,
# generate a hyperlink. If the name we're looking for contains # generate a hyperlink. If the name we're looking for contains
@ -134,9 +108,10 @@ module Generators
end end
end end
##
# Generate a hyperlink for url, labeled with text. Handle the # Generate a hyperlink for url, labeled with text. Handle the
# special cases for img: and link: described under handle_special_HYPEDLINK # special cases for img: and link: described under handle_special_HYPEDLINK
def gen_url(url, text) def gen_url(url, text)
if url =~ /([A-Za-z]+):(.*)/ if url =~ /([A-Za-z]+):(.*)/
type = $1 type = $1
@ -164,6 +139,7 @@ module Generators
end end
end end
##
# And we're invoked with a potential external hyperlink mailto: # And we're invoked with a potential external hyperlink mailto:
# just gets inserted. http: links are checked to see if they # just gets inserted. http: links are checked to see if they
# reference an image. If so, that image gets inserted using an # reference an image. If so, that image gets inserted using an
@ -176,9 +152,9 @@ module Generators
gen_url(url, url) gen_url(url, url)
end 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
# <label>[url] # <label>[url]
#
def handle_special_TIDYLINK(special) def handle_special_TIDYLINK(special)
text = special.text text = special.text
@ -193,15 +169,12 @@ module Generators
end end
##
#####################################################################
#
# Handle common markup tasks for the various Html classes # Handle common markup tasks for the various Html classes
#
module MarkUp module MarkUp
##
# Convert a string in markup format into HTML. We keep a cached # Convert a string in markup format into HTML. We keep a cached
# SimpleMarkup object lying around after the first time we're # SimpleMarkup object lying around after the first time we're
# called per object. # called per object.
@ -251,6 +224,7 @@ module Generators
res res
end end
##
# Qualify a stylesheet URL; if if +css_name+ does not begin with '/' or # Qualify a stylesheet URL; if if +css_name+ does not begin with '/' or
# 'http[s]://', prepend a prefix relative to +path+. Otherwise, return it # 'http[s]://', prepend a prefix relative to +path+. Otherwise, return it
# unmodified. # unmodified.
@ -265,6 +239,7 @@ module Generators
end end
end end
##
# Build a webcvs URL with the given 'url' argument. URLs with a '%s' in them # Build a webcvs URL with the given 'url' argument. URLs with a '%s' in them
# get the file's path sprintfed into them; otherwise they're just catenated # get the file's path sprintfed into them; otherwise they're just catenated
# together. # together.
@ -276,15 +251,14 @@ module Generators
return url + full_path return url + full_path
end end
end end
end end
##
#####################################################################
#
# A Context is built by the parser to represent a container: contexts # A Context is built by the parser to represent a container: contexts
# hold classes, modules, methods, require lists and include lists. # hold classes, modules, methods, require lists and include lists.
# ClassModule and TopLevel are the context objects we process here # ClassModule and TopLevel are the context objects we process here
#
class ContextUser class ContextUser
include MarkUp include MarkUp
@ -296,14 +270,16 @@ module Generators
@options = options @options = options
end end
##
# convenience method to build a hyperlink # convenience method to build a hyperlink
def href(link, cls, name) def href(link, cls, name)
%{<a href="#{link}" class="#{cls}">#{name}</a>} #" %{<a href="#{link}" class="#{cls}">#{name}</a>} #"
end end
# return a reference to outselves to be used as an href= ##
# the form depends on whether we're all in one file # Returns a reference to outselves to be used as an href= the form depends
# or in multiple files # on whether we're all in one file or in multiple files
def as_href(from_path) def as_href(from_path)
if @options.all_one_file if @options.all_one_file
@ -313,10 +289,11 @@ module Generators
end end
end end
# Create a list of HtmlMethod objects for each method ##
# in the corresponding context object. If the @options.show_all # Create a list of HtmlMethod objects for each method in the corresponding
# variable is set (corresponding to the <tt>--all</tt> option, # context object. If the @options.show_all variable is set (corresponding
# we include all methods, otherwise just the public ones. # to the <tt>--all</tt> option, we include all methods, otherwise just the
# public ones.
def collect_methods def collect_methods
list = @context.method_list list = @context.method_list
@ -326,7 +303,9 @@ module Generators
@methods = list.collect {|m| HtmlMethod.new(m, self, @options) } @methods = list.collect {|m| HtmlMethod.new(m, self, @options) }
end end
##
# Build a summary list of all the methods in this context # Build a summary list of all the methods in this context
def build_method_summary_list(path_prefix="") def build_method_summary_list(path_prefix="")
collect_methods unless @methods collect_methods unless @methods
meths = @methods.sort meths = @methods.sort
@ -340,9 +319,10 @@ module Generators
res res
end end
##
# Build a list of aliases for which we couldn't find a # Build a list of aliases for which we couldn't find a
# corresponding method # corresponding method
def build_alias_summary_list(section) def build_alias_summary_list(section)
values = [] values = []
@context.aliases.each do |al| @context.aliases.each do |al|
@ -359,7 +339,9 @@ module Generators
values values
end end
##
# Build a list of constants # Build a list of constants
def build_constants_summary_list(section) def build_constants_summary_list(section)
values = [] values = []
@context.constants.each do |co| @context.constants.each do |co|
@ -382,6 +364,7 @@ module Generators
potentially_referenced_list(context.includes) potentially_referenced_list(context.includes)
end end
##
# Build a list from an array of <i>Htmlxxx</i> items. Look up each # Build a list from an array of <i>Htmlxxx</i> items. Look up each
# in the AllReferences hash: if we find a corresponding entry, # in the AllReferences hash: if we find a corresponding entry,
# we generate a hyperlink to it, otherwise just output the name. # we generate a hyperlink to it, otherwise just output the name.
@ -424,6 +407,7 @@ module Generators
res res
end end
##
# Build an array of arrays of method details. The outer array has up # Build an array of arrays of method details. The outer array has up
# to six entries, public, private, and protected for both class # to six entries, public, private, and protected for both class
# methods, the other for instance methods. The inner arrays contain # methods, the other for instance methods. The inner arrays contain
@ -491,6 +475,7 @@ module Generators
outer outer
end end
##
# Build the structured list of classes and modules contained # Build the structured list of classes and modules contained
# in this context. # in this context.
@ -550,8 +535,9 @@ module Generators
res res
end end
##
# Find a symbol in ourselves or our parent # Find a symbol in ourselves or our parent
def find_symbol(symbol, method=nil) def find_symbol(symbol, method=nil)
res = @context.find_symbol(symbol, method) res = @context.find_symbol(symbol, method)
if res if res
@ -560,6 +546,7 @@ module Generators
res res
end end
##
# create table of contents if we contain sections # create table of contents if we contain sections
def add_table_of_sections def add_table_of_sections
@ -576,11 +563,9 @@ module Generators
@values['toc'] = toc unless toc.empty? @values['toc'] = toc unless toc.empty?
end end
end end
##################################################################### ##
#
# Wrap a ClassModule context # Wrap a ClassModule context
class HtmlClass < ContextUser class HtmlClass < ContextUser
@ -607,8 +592,10 @@ module Generators
AllReferences.add(name, self) AllReferences.add(name, self)
end end
# return the relative file name to store this class in, ##
# which is also its url # Returns the relative file name to store this class in, which is also its
# url
def http_url(full_name, prefix) def http_url(full_name, prefix)
path = full_name.dup path = full_name.dup
if path['<<'] if path['<<']
@ -617,7 +604,6 @@ module Generators
File.join(prefix, path.split("::")) + ".html" File.join(prefix, path.split("::")) + ".html"
end end
def name def name
@context.full_name @context.full_name
end end
@ -759,8 +745,7 @@ module Generators
end end
##################################################################### ##
#
# Handles the mapping of a file's information to HTML. In reality, # Handles the mapping of a file's information to HTML. In reality,
# a file corresponds to a +TopLevel+ object, containing modules, # a file corresponds to a +TopLevel+ object, containing modules,
# classes, and top-level methods. In theory it _could_ contain # classes, and top-level methods. In theory it _could_ contain
@ -891,11 +876,13 @@ module Generators
def <=>(other) def <=>(other)
self.name <=> other.name self.name <=> other.name
end end
end end
##################################################################### ##
class HtmlMethod class HtmlMethod
include MarkUp include MarkUp
attr_reader :context attr_reader :context
@ -932,9 +919,9 @@ module Generators
AllReferences.add(name, self) AllReferences.add(name, self)
end end
# return a reference to outselves to be used as an href= ##
# the form depends on whether we're all in one file # Returns a reference to outselves to be used as an href= the form depends
# or in multiple files # on whether we're all in one file or in multiple files
def as_href(from_path) def as_href(from_path)
if @options.all_one_file if @options.all_one_file
@ -1053,7 +1040,6 @@ module Generators
# Given a sequence of source tokens, mark up the source code # Given a sequence of source tokens, mark up the source code
# to make it look purty. # to make it look purty.
def markup_code(tokens) def markup_code(tokens)
src = "" src = ""
tokens.each do |t| tokens.each do |t|
@ -1088,8 +1074,8 @@ module Generators
src src
end end
# we rely on the fact that the first line of a source code ##
# listing has # We rely on the fact that the first line of a source code listing has
# # File xxxxx, line dddd # # File xxxxx, line dddd
def add_line_numbers(src) def add_line_numbers(src)
@ -1123,17 +1109,51 @@ module Generators
end end
res res
end end
end end
##################################################################### ##
# 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.
class HTMLGenerator class HTMLGenerator
include MarkUp include MarkUp
## ##
# convert a target url to one that is relative to a given # Converts a target url to one that is relative to a given path
# path
def HTMLGenerator.gen_url(path, target) def HTMLGenerator.gen_url(path, target)
from = File.dirname(path) from = File.dirname(path)
@ -1153,9 +1173,9 @@ module Generators
File.join(*from) File.join(*from)
end end
# Generators may need to return specific subclasses depending ##
# on the options they are passed. Because of this # Generators may need to return specific subclasses depending on the
# we create them using a factory # options they are passed. Because of this we create them using a factory
def HTMLGenerator.for(options) def HTMLGenerator.for(options)
AllReferences::reset AllReferences::reset
@ -1172,15 +1192,15 @@ module Generators
protected :new protected :new
end end
# Set up a new HTML generator. Basically all we do here is load ##
# up the correct output temlate # Set up a new HTML generator. Basically all we do here is load up the
# correct output temlate
def initialize(options) #:not-new: def initialize(options) #:not-new:
@options = options @options = options
load_html_template load_html_template
end end
## ##
# Build the initial indices and output objects # Build the initial indices and output objects
# based on an array of TopLevel objects containing # based on an array of TopLevel objects containing
@ -1202,7 +1222,7 @@ module Generators
## ##
# Load up the HTML template specified in the options. # Load up the HTML template specified in the options.
# If the template name contains a slash, use it literally # If the template name contains a slash, use it literally
#
def load_html_template def load_html_template
template = @options.template template = @options.template
unless template =~ %r{/|\\} unless template =~ %r{/|\\}
@ -1218,7 +1238,6 @@ module Generators
## ##
# Write out the style sheet used by the main frames # Write out the style sheet used by the main frames
#
def write_style_sheet def write_style_sheet
template = TemplatePage.new(RDoc::Page::STYLE) template = TemplatePage.new(RDoc::Page::STYLE)
@ -1231,8 +1250,7 @@ module Generators
end end
## ##
# See the comments at the top for a description of the # See the comments at the top for a description of the directory structure
# directory structure
def gen_sub_directories def gen_sub_directories
FileUtils.mkdir_p(FILE_DIR) FileUtils.mkdir_p(FILE_DIR)
@ -1271,7 +1289,7 @@ module Generators
## ##
# Generate all the HTML # Generate all the HTML
#
def generate_html def generate_html
# the individual descriptions for files and classes # the individual descriptions for files and classes
gen_into(@files) gen_into(@files)
@ -1315,7 +1333,6 @@ module Generators
"fr_method_index.html") "fr_method_index.html")
end end
def gen_an_index(collection, title, template, filename) def gen_an_index(collection, title, template, filename)
template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template) template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
res = [] res = []
@ -1338,10 +1355,11 @@ module Generators
end end
end end
# The main index page is mostly a template frameset, but includes ##
# the initial page. If the <tt>--main</tt> option was given, # The main index page is mostly a template frameset, but includes the
# we use this as our main page, otherwise we use the # initial page. If the <tt>--main</tt> option was given, we use this as
# first file specified on the command line. # our main page, otherwise we use the first file specified on the command
# line.
def gen_main_index def gen_main_index
template = TemplatePage.new(RDoc::Page::INDEX) template = TemplatePage.new(RDoc::Page::INDEX)
@ -1358,7 +1376,9 @@ module Generators
end end
end end
# return the url of the main page ##
# Returns the url of the main page
def main_url def main_url
main_page = @options.main_page main_page = @options.main_page
ref = nil ref = nil
@ -1389,13 +1409,8 @@ module Generators
ref ref
end end
end end
######################################################################
class HTMLGeneratorInOne < HTMLGenerator class HTMLGeneratorInOne < HTMLGenerator
def initialize(*args) def initialize(*args)
@ -1417,7 +1432,6 @@ module Generators
generate_xml generate_xml
end end
## ##
# Generate: # Generate:
# #
@ -1448,7 +1462,7 @@ module Generators
## ##
# Generate all the HTML. For the one-file case, we generate # Generate all the HTML. For the one-file case, we generate
# all the information in to one big hash # all the information in to one big hash
#
def generate_xml def generate_xml
values = { values = {
'charset' => @options.charset, 'charset' => @options.charset,
@ -1490,7 +1504,6 @@ module Generators
gen_an_index(HtmlMethod.all_methods, 'Methods') gen_an_index(HtmlMethod.all_methods, 'Methods')
end end
def gen_an_index(collection, title) def gen_an_index(collection, title)
res = [] res = []
collection.sort.each do |f| collection.sort.each do |f|
@ -1507,4 +1520,6 @@ module Generators
end end
end end
end end

View file

@ -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 'rdoc/options' require 'rdoc/options'
require 'rdoc/template' require 'rdoc/template'
require 'rdoc/markup/simple_markup' require 'rdoc/markup/simple_markup'
@ -47,12 +11,11 @@ require 'rdoc/ri/ri_descriptions'
module Generators module Generators
class RIGenerator class RIGenerator
# Generators may need to return specific subclasses depending ##
# on the options they are passed. Because of this # Generators may need to return specific subclasses depending on the
# we create them using a factory # options they are passed. Because of this we create them using a factory
def RIGenerator.for(options) def RIGenerator.for(options)
new(options) new(options)
@ -62,8 +25,9 @@ module Generators
protected :new protected :new
end end
# Set up a new HTML generator. Basically all we do here is load ##
# up the correct output temlate # Set up a new HTML generator. Basically all we do here is load up the
# correct output temlate
def initialize(options) #:not-new: def initialize(options) #:not-new:
@options = options @options = options
@ -72,11 +36,9 @@ module Generators
@to_flow = SM::ToFlow.new @to_flow = SM::ToFlow.new
end end
## ##
# Build the initial indices and output objects # Build the initial indices and output objects based on an array of
# based on an array of TopLevel objects containing # TopLevel objects containing the extracted information.
# the extracted information.
def generate(toplevels) def generate(toplevels)
RDoc::TopLevel.all_classes_and_modules.each do |cls| RDoc::TopLevel.all_classes_and_modules.each do |cls|
@ -163,8 +125,8 @@ module Generators
private private
# return a list of class and instance methods that we'll be ##
# documenting # Returns a list of class and instance methods that we'll be documenting
def method_list(cls) def method_list(cls)
list = cls.method_list list = cls.method_list
@ -222,12 +184,11 @@ module Generators
@markup.convert(content, @to_flow) @markup.convert(content, @to_flow)
end end
##
# By default we replace existing classes with the # By default we replace existing classes with the same name. If the
# same name. If the --merge option was given, we instead # --merge option was given, we instead merge this definition into an
# merge this definition into an existing class. We add # existing class. We add our methods, aliases, etc to that class, but do
# our methods, aliases, etc to that class, but do not # not change the class's description.
# change the class's description.
def update_or_replace(cls_desc) def update_or_replace(cls_desc)
old_cls = nil old_cls = nil
@ -262,5 +223,8 @@ module Generators
@ri_writer.add_class(old_desc) @ri_writer.add_class(old_desc)
end end
end end
end end
end end

View file

@ -1,4 +1,3 @@
require 'rdoc/options' require 'rdoc/options'
require 'rdoc/markup/simple_markup' require 'rdoc/markup/simple_markup'
require 'rdoc/markup/simple_markup/to_html' require 'rdoc/markup/simple_markup/to_html'
@ -6,16 +5,18 @@ require 'rdoc/generators/html_generator'
module Generators module Generators
##
# Generate XML output as one big file # Generate XML output as one big file
class XMLGenerator < HTMLGenerator class XMLGenerator < HTMLGenerator
##
# Standard generator factory # Standard generator factory
def XMLGenerator.for(options) def XMLGenerator.for(options)
XMLGenerator.new(options) XMLGenerator.new(options)
end end
def initialize(*args) def initialize(*args)
super super
end end
@ -35,7 +36,6 @@ module Generators
generate_xml generate_xml
end end
## ##
# Generate: # Generate:
# #
@ -66,7 +66,7 @@ module Generators
## ##
# Generate all the HTML. For the one-file case, we generate # Generate all the HTML. For the one-file case, we generate
# all the information in to one big hash # all the information in to one big hash
#
def generate_xml def generate_xml
values = { values = {
'charset' => @options.charset, 'charset' => @options.charset,
@ -107,7 +107,6 @@ module Generators
gen_an_index(HtmlMethod.all_methods, 'Methods') gen_an_index(HtmlMethod.all_methods, 'Methods')
end end
def gen_an_index(collection, title) def gen_an_index(collection, title)
res = [] res = []
collection.sort.each do |f| collection.sort.each do |f|
@ -126,3 +125,4 @@ module Generators
end end
end end