mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
Import RDoc 2.5
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@27147 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
drbrain
parent
9b40cdfe8c
commit
46580b5147
176 changed files with 17841 additions and 16457 deletions
|
|
@ -1,299 +1,159 @@
|
|||
require 'rubygems'
|
||||
require 'minitest/unit'
|
||||
require 'rdoc/generator'
|
||||
require 'rdoc/stats'
|
||||
require 'minitest/autorun'
|
||||
require 'rdoc/rdoc'
|
||||
require 'rdoc/code_objects'
|
||||
require 'rdoc/markup/to_html_crossref'
|
||||
require 'rdoc/parser/ruby'
|
||||
require File.expand_path '../xref_test_case', __FILE__
|
||||
|
||||
require 'pathname'
|
||||
class TestRDocMarkupToHtmlCrossref < XrefTestCase
|
||||
|
||||
class TestRDocMarkupToHtmlCrossref < MiniTest::Unit::TestCase
|
||||
def setup
|
||||
super
|
||||
|
||||
#
|
||||
# This method parses a source file and returns a Hash mapping
|
||||
# class names (Strings) to RDoc::Generator::Class instances
|
||||
# (classes), which can be used to create RDoc::Markup::ToHtmlCrossref
|
||||
# instances. The unit tests only test against classes starting with
|
||||
# Ref_, so this method only includes such classes in the Hash.
|
||||
#
|
||||
def create_class_hash
|
||||
# The relative gem would help here...
|
||||
# @source_file_name must be cleaned because rdoc does not deal
|
||||
# well with paths containing "." or "..".
|
||||
curr_file = Pathname.new(__FILE__)
|
||||
@source_file_name = curr_file.dirname + "rdoc_markup_to_html_crossref_reference.rb"
|
||||
@source_file_name = @source_file_name.cleanpath.to_s
|
||||
|
||||
RDoc::TopLevel.reset
|
||||
|
||||
# Reset RDoc::Generator::Method so that the method sequence number starts
|
||||
# at 1, making the method sequence numbers for the methods in the Ref_
|
||||
# predicable.
|
||||
RDoc::Generator::Method.reset
|
||||
top_level = RDoc::TopLevel.new @source_file_name
|
||||
|
||||
options = RDoc::Options.new
|
||||
options.quiet = true
|
||||
|
||||
# If this is false, then RDoc::Generator::Method will attempt to create
|
||||
# an HTML file containing the method source code when being instantiated,
|
||||
# which does not work in the context of this unit test.
|
||||
#
|
||||
# RDoc::Generator::Method needs to be refactored so that this does *not*
|
||||
# happen as part of instantiation.
|
||||
options.inline_source = true
|
||||
|
||||
stats = RDoc::Stats.new 0
|
||||
|
||||
parser = RDoc::Parser::Ruby.new(top_level,
|
||||
@source_file_name,
|
||||
IO.read(@source_file_name),
|
||||
options,
|
||||
stats)
|
||||
top_levels = []
|
||||
top_levels.push(parser.scan())
|
||||
|
||||
files, classes = RDoc::Generator::Context.build_indices(top_levels, options)
|
||||
|
||||
class_hash = {}
|
||||
classes.each do |klass|
|
||||
if(klass.name.include?("Ref_"))
|
||||
class_hash[klass.name] = klass
|
||||
end
|
||||
end
|
||||
|
||||
return class_hash
|
||||
@xref = RDoc::Markup::ToHtmlCrossref.new 'index.html', @c1, true
|
||||
end
|
||||
|
||||
#
|
||||
# This method uses xref to cross-reference String reference and
|
||||
# asserts that xref.convert(reference) is equal
|
||||
# to String expected_result.
|
||||
#
|
||||
def verify_convert(xref, reference, expected_result)
|
||||
# Everything converted in the tests will be within paragraph markup, so
|
||||
# add paragraph markup to the expected result.
|
||||
actual_expected_result = "<p>\n#{expected_result}\n</p>\n"
|
||||
|
||||
result = xref.convert(reference)
|
||||
|
||||
# RDoc::Markup::ToHtml word-wraps lines. It is tricky to predict where
|
||||
# a line will be wrapped except that it will happen on a space, so replace
|
||||
# all newlines with spaces in order to not have to worry about this.
|
||||
actual_expected_result.gsub!(/\n/, " ")
|
||||
result.gsub!(/\n/, " ")
|
||||
|
||||
begin
|
||||
assert_equal actual_expected_result, result
|
||||
rescue MiniTest::Assertion => e
|
||||
bt = caller(2)
|
||||
raise e, [e.message, *bt.grep(/\A#{Regexp.quote(__FILE__)}:/o)].join("\n"), bt
|
||||
end
|
||||
def assert_ref(path, ref)
|
||||
assert_equal "<p>\n<a href=\"#{path}\">#{ref}</a>\n</p>\n",
|
||||
@xref.convert(ref)
|
||||
end
|
||||
|
||||
#
|
||||
# This method verifies that xref generates no cross-reference link for
|
||||
# String reference.
|
||||
#
|
||||
def verify_no_crossref(xref, reference)
|
||||
if(reference[0, 1] == "\\") # Remove the markup suppression character
|
||||
expected_result = reference[1, reference.length() - 1]
|
||||
else
|
||||
expected_result = reference
|
||||
end
|
||||
|
||||
verify_convert(xref, reference, expected_result)
|
||||
def refute_ref(body, ref)
|
||||
assert_equal "<p>\n#{body}\n</p>\n", @xref.convert(ref)
|
||||
end
|
||||
|
||||
#
|
||||
# This method verifies that xref generates a cross-reference link to
|
||||
# class_name (String) for String reference.
|
||||
#
|
||||
def verify_class_crossref(xref, reference, class_name)
|
||||
class_file_name = class_name.gsub(/::/, "/")
|
||||
def test_handle_special_CROSSREF_C2
|
||||
@xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C2.html', @c2, true
|
||||
|
||||
result = "<a href=\"../classes/#{class_file_name}.html\">#{reference}</a>"
|
||||
refute_ref '#m', '#m'
|
||||
|
||||
verify_convert xref, reference, result
|
||||
assert_ref '../C2/C3.html', 'C2::C3'
|
||||
assert_ref '../C2/C3.html#M000002', 'C2::C3#m'
|
||||
assert_ref '../C2/C3/H1.html', 'C3::H1'
|
||||
assert_ref '../C4.html', 'C4'
|
||||
|
||||
# TODO there is a C3::H2 in the top-level namespace and RDoc should follow
|
||||
# constant scoping rules
|
||||
refute_ref 'C3::H2', 'C3::H2'
|
||||
refute_ref 'H1', 'H1'
|
||||
end
|
||||
|
||||
#
|
||||
# This method verifies that xref generates a cross-reference link to method
|
||||
# method_seq (String, e.g, "M000001") in class_name (String) for
|
||||
# String reference.
|
||||
#
|
||||
def verify_method_crossref(xref, reference, class_name, method_seq)
|
||||
class_file_name = class_name.gsub(/::/, "/")
|
||||
def test_handle_special_CROSSREF_C2_C3
|
||||
@xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C2/C3.html', @c2_c3, true
|
||||
|
||||
result = "<a href=\"../classes/#{class_file_name}.html##{method_seq}\">#{reference}</a>"
|
||||
assert_ref '../../C2/C3.html#M000002', '#m'
|
||||
|
||||
verify_convert xref, reference, result
|
||||
assert_ref '../../C2/C3.html', 'C3'
|
||||
assert_ref '../../C2/C3.html#M000002', 'C3#m'
|
||||
|
||||
assert_ref '../../C2/C3/H1.html', 'H1'
|
||||
assert_ref '../../C2/C3/H1.html', 'C3::H1'
|
||||
|
||||
assert_ref '../../C4.html', 'C4'
|
||||
|
||||
refute_ref 'C3::H2', 'C3::H2'
|
||||
end
|
||||
|
||||
#
|
||||
# This method verifies that xref generates a cross-reference link to
|
||||
# file_name (String) for String reference.
|
||||
#
|
||||
def verify_file_crossref(xref, reference, file_name)
|
||||
generated_document_path = Pathname.new("../files/#{file_name.gsub(/\./, '_')}.html").cleanpath.to_s
|
||||
result = "<a href=\"#{generated_document_path}\">#{reference}</a>"
|
||||
def test_handle_special_CROSSREF_C3
|
||||
@xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C3.html', @c3, true
|
||||
|
||||
verify_convert xref, reference, result
|
||||
assert_ref '../C3.html', 'C3'
|
||||
|
||||
refute_ref '#m', '#m'
|
||||
refute_ref 'C3#m', 'C3#m'
|
||||
|
||||
assert_ref '../C3/H1.html', 'H1'
|
||||
|
||||
assert_ref '../C3/H1.html', 'C3::H1'
|
||||
assert_ref '../C3/H2.html', 'C3::H2'
|
||||
|
||||
assert_ref '../C4.html', 'C4'
|
||||
end
|
||||
|
||||
#
|
||||
# This method verifies that several invariant cross-references are
|
||||
# (or are not) generated.
|
||||
#
|
||||
def verify_invariant_crossrefs(xref)
|
||||
# bogus does not exist and so no cross-reference should be generated.
|
||||
verify_no_crossref xref, "bogus"
|
||||
verify_no_crossref xref, "\\bogus"
|
||||
def test_handle_special_CROSSREF_C4
|
||||
@xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C4.html', @c4, true
|
||||
|
||||
# Ref_Class1 is in the top-level namespace, and so a cross-reference always
|
||||
# should be generated, unless markup is suppressed.
|
||||
verify_class_crossref xref, "Ref_Class1", "Ref_Class1"
|
||||
verify_no_crossref xref, "\\Ref_Class1"
|
||||
|
||||
# Ref_Class2 is in the top-level namespace, and so a cross-reference always
|
||||
# should be generated for it and for its nested classes.
|
||||
verify_class_crossref xref, "Ref_Class2", "Ref_Class2"
|
||||
verify_class_crossref xref, "Ref_Class2::Ref_Class3", "Ref_Class2::Ref_Class3"
|
||||
verify_method_crossref xref, "Ref_Class2::Ref_Class3#method", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_method_crossref xref, "Ref_Class2::Ref_Class3#method()", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_method_crossref xref, "Ref_Class2::Ref_Class3.method()", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_method_crossref xref, "Ref_Class2::Ref_Class3.method(*)", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_class_crossref xref, "Ref_Class2::Ref_Class3::Helper1", "Ref_Class2::Ref_Class3::Helper1"
|
||||
verify_method_crossref xref, "Ref_Class2::Ref_Class3::Helper1#method?", "Ref_Class2::Ref_Class3::Helper1", "M000002"
|
||||
|
||||
# The hyphen character is not a valid class/method separator character, so
|
||||
# rdoc just generates a class cross-reference (perhaps it should not
|
||||
# generate anything?).
|
||||
result = "<a href=\"../classes/Ref_Class2/Ref_Class3.html\">Ref_Class2::Ref_Class3</a>;method(*)"
|
||||
verify_convert xref, "Ref_Class2::Ref_Class3;method(*)", result
|
||||
|
||||
# There is one Ref_Class3 nested in Ref_Class2 and one defined in the
|
||||
# top-level namespace; regardless, ::Ref_Class3 (Ref_Class3 relative
|
||||
# to the top-level namespace) always should generate a link to the
|
||||
# top-level Ref_Class3 (unless of course cross-references are suppressed).
|
||||
verify_class_crossref xref, "::Ref_Class3", "Ref_Class3"
|
||||
verify_no_crossref xref, "\\::Ref_Class3"
|
||||
verify_class_crossref xref, "::Ref_Class3::Helper1", "Ref_Class3::Helper1"
|
||||
verify_class_crossref xref, "::Ref_Class3::Helper2", "Ref_Class3::Helper2"
|
||||
|
||||
#
|
||||
# Ref_Class3::Helper1 does not have method method.
|
||||
#
|
||||
verify_no_crossref xref, "::Ref_Class3::Helper1#method"
|
||||
verify_no_crossref xref, "\\::Ref_Class3::Helper1#method"
|
||||
|
||||
# References to Ref_Class2 relative to the top-level namespace always should
|
||||
# generate links to Ref_Class2.
|
||||
verify_method_crossref xref, "::Ref_Class2::Ref_Class3#method", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_method_crossref xref, "::Ref_Class2::Ref_Class3#method()", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_method_crossref xref, "::Ref_Class2::Ref_Class3#method(*)", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_class_crossref xref, "::Ref_Class2::Ref_Class3::Helper1", "Ref_Class2::Ref_Class3::Helper1"
|
||||
verify_no_crossref xref, "\\::Ref_Class2::Ref_Class3#method(*)"
|
||||
|
||||
# Suppressing cross-references always should suppress the generation of
|
||||
# links.
|
||||
verify_no_crossref xref, "\\#method"
|
||||
verify_no_crossref xref, "\\#method()"
|
||||
verify_no_crossref xref, "\\#method(*)"
|
||||
|
||||
# Links never should be generated for words solely consisting of lowercase
|
||||
# letters, because too many links would get generated by mistake (i.e., the
|
||||
# word "new" always would be a link).
|
||||
verify_no_crossref xref, "method"
|
||||
|
||||
# A link always should be generated for a file name.
|
||||
verify_file_crossref xref, @source_file_name, @source_file_name
|
||||
|
||||
# References should be generated correctly for a class scoped within
|
||||
# a class of the same name.
|
||||
verify_class_crossref xref, "Ref_Class4::Ref_Class4", "Ref_Class4::Ref_Class4"
|
||||
# C4 ref inside a C4 containing a C4 should resolve to the contained class
|
||||
assert_ref '../C4/C4.html', 'C4'
|
||||
end
|
||||
|
||||
def test_handle_special_CROSSREF_no_underscore
|
||||
class_hash = create_class_hash
|
||||
def test_handle_special_CROSSREF_C4_C4
|
||||
@xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C4/C4.html', @c4_c4, true
|
||||
|
||||
# Note that we instruct the ToHtmlCrossref instance to show hashes so that
|
||||
# an exception won't have to be made for words starting with a '#'.
|
||||
# I'm also not convinced that the current behavior of the rdoc code
|
||||
# is correct since, without this, it strips the leading # from all
|
||||
# words, whether or not they end up as cross-references.
|
||||
#
|
||||
# After the behavior has been sorted out, this can be changed.
|
||||
#
|
||||
# Create a variety of RDoc::Markup::ToHtmlCrossref instances, for
|
||||
# different classes, and test the cross-references generated by
|
||||
# each.
|
||||
klass = class_hash["Ref_Class1"]
|
||||
xref = RDoc::Markup::ToHtmlCrossref.new 'from_path', klass, true
|
||||
verify_invariant_crossrefs xref
|
||||
verify_class_crossref xref, "Ref_Class3", "Ref_Class3"
|
||||
verify_no_crossref xref, "Ref_Class3#method"
|
||||
verify_no_crossref xref, "#method"
|
||||
verify_class_crossref xref, "Ref_Class3::Helper1", "Ref_Class3::Helper1"
|
||||
verify_class_crossref xref, "Ref_Class3::Helper2", "Ref_Class3::Helper2"
|
||||
verify_no_crossref xref, "Helper1"
|
||||
verify_class_crossref xref, "Ref_Class4", "Ref_Class4"
|
||||
|
||||
klass = class_hash["Ref_Class2"]
|
||||
xref = RDoc::Markup::ToHtmlCrossref.new 'from_path', klass, true
|
||||
verify_invariant_crossrefs xref
|
||||
verify_class_crossref xref, "Ref_Class3", "Ref_Class2::Ref_Class3"
|
||||
verify_method_crossref xref, "Ref_Class3#method", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_no_crossref xref, "#method"
|
||||
verify_class_crossref xref, "Ref_Class3::Helper1", "Ref_Class2::Ref_Class3::Helper1"
|
||||
verify_class_crossref xref, "Ref_Class4", "Ref_Class4"
|
||||
|
||||
# This one possibly is an rdoc bug...
|
||||
# Ref_Class2 has a nested Ref_Class3, but
|
||||
# Ref_Class2::Ref_Class3::Helper2 does not exist.
|
||||
# On the other hand, there is a Ref_Class3::Helper2
|
||||
# in the top-level namespace... Should rdoc stop
|
||||
# looking if it finds one class match?
|
||||
verify_no_crossref xref, "Ref_Class3::Helper2"
|
||||
verify_no_crossref xref, "Helper1"
|
||||
|
||||
klass = class_hash["Ref_Class2::Ref_Class3"]
|
||||
xref = RDoc::Markup::ToHtmlCrossref.new 'from_path', klass, true
|
||||
verify_invariant_crossrefs xref
|
||||
verify_class_crossref xref, "Ref_Class3", "Ref_Class2::Ref_Class3"
|
||||
verify_method_crossref xref, "Ref_Class3#method", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_method_crossref xref, "#method", "Ref_Class2::Ref_Class3", "M000001"
|
||||
verify_class_crossref xref, "Ref_Class3::Helper1", "Ref_Class2::Ref_Class3::Helper1"
|
||||
verify_no_crossref xref, "Ref_Class3::Helper2"
|
||||
verify_class_crossref xref, "Helper1", "Ref_Class2::Ref_Class3::Helper1"
|
||||
verify_class_crossref xref, "Ref_Class4", "Ref_Class4"
|
||||
|
||||
klass = class_hash["Ref_Class3"]
|
||||
xref = RDoc::Markup::ToHtmlCrossref.new 'from_path', klass, true
|
||||
verify_invariant_crossrefs xref
|
||||
verify_class_crossref xref, "Ref_Class3", "Ref_Class3"
|
||||
verify_no_crossref xref, "Ref_Class3#method"
|
||||
verify_no_crossref xref, "#method"
|
||||
verify_class_crossref xref, "Ref_Class3::Helper1", "Ref_Class3::Helper1"
|
||||
verify_class_crossref xref, "Ref_Class3::Helper2", "Ref_Class3::Helper2"
|
||||
verify_class_crossref xref, "Helper1", "Ref_Class3::Helper1"
|
||||
verify_class_crossref xref, "Ref_Class4", "Ref_Class4"
|
||||
|
||||
klass = class_hash["Ref_Class4"]
|
||||
xref = RDoc::Markup::ToHtmlCrossref.new 'from_path', klass, true
|
||||
verify_invariant_crossrefs xref
|
||||
# A Ref_Class4 reference inside a Ref_Class4 class containing a
|
||||
# Ref_Class4 class should resolve to the contained class.
|
||||
verify_class_crossref xref, "Ref_Class4", "Ref_Class4::Ref_Class4"
|
||||
|
||||
klass = class_hash["Ref_Class4::Ref_Class4"]
|
||||
xref = RDoc::Markup::ToHtmlCrossref.new 'from_path', klass, true
|
||||
verify_invariant_crossrefs xref
|
||||
# A Ref_Class4 reference inside a Ref_Class4 class contained within
|
||||
# a Ref_Class4 class should resolve to the inner Ref_Class4 class.
|
||||
verify_class_crossref xref, "Ref_Class4", "Ref_Class4::Ref_Class4"
|
||||
# A C4 reference inside a C4 class contained within a C4 class should
|
||||
# resolve to the inner C4 class.
|
||||
assert_ref '../../C4/C4.html', 'C4'
|
||||
end
|
||||
|
||||
def test_handle_special_CROSSREF_class
|
||||
assert_ref 'C1.html', 'C1'
|
||||
refute_ref 'H1', 'H1'
|
||||
|
||||
assert_ref 'C2.html', 'C2'
|
||||
assert_ref 'C2/C3.html', 'C2::C3'
|
||||
assert_ref 'C2/C3/H1.html', 'C2::C3::H1'
|
||||
|
||||
assert_ref 'C3.html', '::C3'
|
||||
assert_ref 'C3/H1.html', '::C3::H1'
|
||||
|
||||
assert_ref 'C4/C4.html', 'C4::C4'
|
||||
end
|
||||
|
||||
def test_handle_special_CROSSREF_file
|
||||
assert_ref 'xref_data_rb.html', 'xref_data.rb'
|
||||
end
|
||||
|
||||
def test_handle_special_CROSSREF_method
|
||||
refute_ref 'm', 'm'
|
||||
assert_ref 'C1.html#M000000', '#m'
|
||||
|
||||
assert_ref 'C1.html#M000000', 'C1#m'
|
||||
assert_ref 'C1.html#M000000', 'C1#m()'
|
||||
assert_ref 'C1.html#M000000', 'C1#m(*)'
|
||||
|
||||
assert_ref 'C1.html#M000000', 'C1.m'
|
||||
assert_ref 'C1.html#M000000', 'C1.m()'
|
||||
assert_ref 'C1.html#M000000', 'C1.m(*)'
|
||||
|
||||
# HACK should this work
|
||||
#assert_ref 'classes/C1.html#M000001', 'C1::m'
|
||||
#assert_ref 'classes/C1.html#M000001', 'C1::m()'
|
||||
#assert_ref 'classes/C1.html#M000001', 'C1::m(*)'
|
||||
|
||||
assert_ref 'C2/C3.html#M000002', 'C2::C3#m'
|
||||
|
||||
assert_ref 'C2/C3.html#M000002', 'C2::C3.m'
|
||||
|
||||
assert_ref 'C2/C3/H1.html#M000003', 'C2::C3::H1#m?'
|
||||
|
||||
assert_ref 'C2/C3.html#M000002', '::C2::C3#m'
|
||||
assert_ref 'C2/C3.html#M000002', '::C2::C3#m()'
|
||||
assert_ref 'C2/C3.html#M000002', '::C2::C3#m(*)'
|
||||
end
|
||||
|
||||
def test_handle_special_CROSSREF_no_ref
|
||||
assert_equal '', @xref.convert('')
|
||||
|
||||
refute_ref 'bogus', 'bogus'
|
||||
refute_ref 'bogus', '\bogus'
|
||||
refute_ref '\bogus', '\\\bogus'
|
||||
|
||||
refute_ref '#n', '\#n'
|
||||
refute_ref '#n()', '\#n()'
|
||||
refute_ref '#n(*)', '\#n(*)'
|
||||
|
||||
refute_ref 'C1', '\C1'
|
||||
refute_ref '::C3', '\::C3'
|
||||
|
||||
refute_ref '::C3::H1#n', '::C3::H1#n'
|
||||
refute_ref '::C3::H1#n(*)', '::C3::H1#n(*)'
|
||||
refute_ref '::C3::H1#n', '\::C3::H1#n'
|
||||
end
|
||||
|
||||
def test_handle_special_CROSSREF_special
|
||||
assert_equal "<p>\n<a href=\"C2/C3.html\">C2::C3</a>;method(*)\n</p>\n",
|
||||
@xref.convert('C2::C3;method(*)')
|
||||
end
|
||||
|
||||
end
|
||||
|
||||
MiniTest::Unit.autorun
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue