Permalink
Browse files

Update TomDoc support to 1.0.0-rc1

  • Loading branch information...
1 parent f506c68 commit 0318fae5e6f37d2677a860c9656ed643b1a02f79 @drbrain drbrain committed Sep 25, 2011
View
@@ -12,10 +12,10 @@
pages.
* HTML output is now using HTML 5.
* RDoc supports additional documentation types:
- * TomDoc 1.0.0-pre
+ * TomDoc 1.0.0-rc1
* RD format
- The default format can be set via the <tt>--markup</tt> option.
+ The default markup can be set via the <tt>--markup</tt> option.
The format of documentation in a particular file can be specified by the
+:markup:+ directive. If the :markup: directive is in the first comment
View
@@ -3,6 +3,9 @@ The items below are may not be implemented as ideas change.
=== RDoc 3.10
* TomDoc 1.0.0-rc1
+* TomDoc Examples should always be highlighted as ruby
+* RDoc::Document and RDoc::Comment need to accept an RDoc::TopLevel for
+ file/location
=== RDoc 3.11
@@ -16,4 +19,9 @@ API changes to RDoc
* RDoc::TopLevel#add_method should automatically create the appropriate method
class rather than requiring one be passed in.
+* RDoc::CodeObject
+ * Move into own namespace
+ * Rename TopLevel to File
+ * Rename Context to Container
+ * Rename NormalClass to Class
View
@@ -210,5 +210,12 @@ def text= text
@text = text
end
+ ##
+ # Returns true if this comment is in TomDoc format.
+
+ def tomdoc?
+ @format == 'tomdoc'
+ end
+
end
@@ -5,7 +5,7 @@
<ul class="link-list">
<% klass.each_method do |meth| %>
- <li><a href="#<%= meth.aref %>"><%= meth.singleton ? '::' : '#' %><%= meth.name %></a>
+ <li><a href="#<%= meth.aref %>"><%= meth.singleton ? '::' : '#' %><%= h meth.name %></a>
<% end %>
</ul>
</nav>
@@ -104,7 +104,7 @@
<% if method.call_seq then %>
<% method.call_seq.strip.split("\n").each_with_index do |call_seq, i| %>
<div class="method-heading">
- <span class="method-callseq"><%= call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w+\./m, '') %></span>
+ <span class="method-callseq"><%= h call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w+\./m, '') %></span>
<% if i == 0 then %>
<span class="method-click-advice">click to toggle source</span>
<% end %>
View
@@ -736,7 +736,8 @@ def parse_constant container, tk, comment
# Generates an RDoc::Method or RDoc::Attr from +comment+ by looking for
# :method: or :attr: directives in +comment+.
- def parse_comment(container, tk, comment)
+ def parse_comment container, tk, comment
+ return parse_comment_tomdoc container, tk, comment if @markup == 'tomdoc'
column = tk.char_no
offset = tk.seek
line_no = tk.line_no
@@ -797,6 +798,44 @@ def parse_comment(container, tk, comment)
true
end
+ ##
+ # Creates an RDoc::Method on +container+ from +comment+ if there is a
+ # Signature section in the comment
+
+ def parse_comment_tomdoc container, tk, comment
+ return unless signature = RDoc::TomDoc.signature(comment)
+ column = tk.char_no
+ offset = tk.seek
+ line_no = tk.line_no
+
+ name, = signature.split %r%[ \(]%, 2
+
+ meth = RDoc::GhostMethod.new get_tkread, name
+ meth.record_location @top_level
+ meth.offset = offset
+ meth.line = line_no
+
+ meth.start_collecting_tokens
+ indent = TkSPACE.new 0, 1, 1
+ indent.set_text " " * offset
+
+ position_comment = TkCOMMENT.new 0, line_no, 1
+ position_comment.set_text "# File #{@top_level.absolute_name}, line #{line_no}"
+ meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
+
+ meth.call_seq = signature
+
+ comment.normalize
+
+ return unless meth.name
+
+ container.add_method meth
+
+ meth.comment = comment
+
+ @stats.add_method meth
+ end
+
##
# Parses an +include+ in +context+ with +comment+
View
@@ -84,6 +84,41 @@ def self.parse text
doc
end
+ # Internal: Extracts the Signature section's method signature
+ #
+ # comment - An RDoc::Comment that will be parsed and have the signature
+ # extracted
+ #
+ # Returns a String containing the signature and nil if not
+
+ def self.signature comment
+ return unless comment.tomdoc?
+
+ document = comment.parse
+
+ signature = nil
+ found_heading = false
+ found_signature = false
+
+ document.parts.delete_if do |part|
+ next false if found_signature
+
+ found_heading ||=
+ RDoc::Markup::Heading === part && part.text == 'Signature'
+
+ next false unless found_heading
+
+ next true if RDoc::Markup::BlankLine === part
+
+ if RDoc::Markup::Verbatim === part then
+ signature = part
+ found_signature = true
+ end
+ end
+
+ signature and signature.text
+ end
+
# Internal: Builds a paragraph from the token stream
#
# margin - Unused
@@ -309,6 +309,14 @@ def test_text_equals_parsed
refute_equal document, @comment.parse
end
+ def test_tomdoc_eh
+ refute @comment.tomdoc?
+
+ @comment.format = 'tomdoc'
+
+ assert @comment.tomdoc?
+ end
+
def test_parse
parsed = @comment.parse
@@ -2320,6 +2320,42 @@ def m
assert_equal 'rd', c.method_list.first.comment.format
end
+ def test_scan_tomdoc_meta
+ util_parser <<-RUBY
+# :markup: tomdoc
+
+class C
+
+ # Signature
+ #
+ # find_by_<field>[_and_<field>...](args)
+ #
+ # field - A field name.
+
+end
+
+ RUBY
+
+ @parser.scan
+
+ c = @top_level.classes.first
+
+ m = c.method_list.first
+
+ assert_equal "find_by_<field>[_and_<field>...]", m.name
+ assert_equal "find_by_<field>[_and_<field>...](args)\n", m.call_seq
+
+ expected =
+ @RM::Document.new(
+ @RM::Heading.new(3, 'Signature'),
+ @RM::List.new(:NOTE,
+ @RM::ListItem.new('field',
+ @RM::Paragraph.new('A field name.'))))
+ expected.file = @top_level.absolute_name
+
+ assert_equal expected, m.comment.parse
+ end
+
def test_stopdoc_after_comment
util_parser <<-EOS
module Bar
View
@@ -5,6 +5,8 @@ class TestRDocTomDoc < RDoc::TestCase
def setup
super
+ @top_level = RDoc::TopLevel.new 'file.rb'
+
@TD = RDoc::TomDoc
@td = @TD.new
end
@@ -36,6 +38,93 @@ def test_class_add_post_processor
assert_equal "# Do some stuff\n", comment.text
end
+ def test_class_signature
+ c = comment <<-COMMENT
+Signature
+
+ method_<here>(args)
+
+here - something
+ COMMENT
+ c.format = 'tomdoc'
+
+ signature = @TD.signature c
+
+ assert_equal "method_<here>(args)\n", signature
+ end
+
+ def test_class_signature_no_space
+ c = comment <<-COMMENT
+Signature
+ method_<here>(args)
+
+here - something
+ COMMENT
+ c.format = 'tomdoc'
+
+ signature = @TD.signature c
+
+ assert_equal "method_<here>(args)\n", signature
+
+ expected =
+ @RM::Document.new(
+ @RM::Heading.new(3, 'Signature'),
+ @RM::List.new(:NOTE,
+ @RM::ListItem.new('here',
+ @RM::Paragraph.new('something'))))
+ expected.file = @top_level.absolute_name
+
+ assert_equal expected, c.parse
+ end
+
+ def test_class_signature_none
+ c = comment ''
+ c.format = 'tomdoc'
+
+ assert_nil @TD.signature c
+ end
+
+ def test_class_rdoc
+ c = comment <<-COMMENT
+=== Signature
+
+ method_<here>(args)
+
+here - something
+ COMMENT
+ c.format = 'rdoc'
+
+ signature = @TD.signature c
+
+ assert_nil signature
+ end
+
+ def test_class_signature_two_space
+ c = comment <<-COMMENT
+Signature
+
+
+ method_<here>(args)
+
+here - something
+ COMMENT
+ c.format = 'tomdoc'
+
+ signature = @TD.signature c
+
+ assert_equal "method_<here>(args)\n", signature
+
+ expected =
+ @RM::Document.new(
+ @RM::Heading.new(3, 'Signature'),
+ @RM::List.new(:NOTE,
+ @RM::ListItem.new('here',
+ @RM::Paragraph.new('something'))))
+ expected.file = @top_level.absolute_name
+
+ assert_equal expected, c.parse
+ end
+
def test_parse_paragraph
text = "Public: Do some stuff\n"

0 comments on commit 0318fae

Please sign in to comment.