Merging in docblock annotations.

Closes issue #34.

bin/rocco

@@ -8,6 +8,7 @@
 #/                          The string to recognize as a comment marker
 #/   -o, --output=<dir>     Directory where generated HTML files are written
 #/   -t, --template=<path>  The file to use as template when rendering HTML
+#/   -d, --docblocks        Parse Docblock @annotations in comments
 #/       --help             Show this help message
 
 require 'optparse'
@@ -39,6 +40,7 @@ ARGV.options { |o|
   o.on("-l", "--language=LANG") { |lang| options[:language] = lang }
   o.on("-c", "--comment-chars=CHARS") { |chars| options[:comment_chars] = Regexp.escape(chars) }
   o.on("-t", "--template=TEMPLATE") { |template| options[:template_file] = template }
+  o.on("-d", "--docblocks") { options[:docblocks] = true }
   o.on_tail("-h", "--help") { usage($stdout, 0) }
   o.parse!
 } or abort_with_note

lib/rocco.rb

@@ -383,11 +383,26 @@ class Rocco
     [docs_blocks, code_blocks]
   end
 
+  # Take a list of block comments and convert Docblock @annotations to
+  # Markdown syntax.
+  def docblock(docs)
+    docs.map do |doc|
+      doc.split("\n").map do |line|
+        line.match(/^@\w+/) ? line.sub(/^@(\w+)\s+/, '> **\1** ')+"  " : line
+      end.join("\n")
+    end
+  end
+
   # Take the result of `split` and apply Markdown formatting to comments and
   # syntax highlighting to source code.
   def highlight(blocks)
     docs_blocks, code_blocks = blocks
 
+    # Pre-process Docblock @annotations.
+    if @options[:docblocks]
+      docs_blocks = docblock(docs_blocks)
+    end
+
     # Combine all docs blocks into a single big markdown document with section
     # dividers and run through the Markdown processor. Then split it back out
     # into separate sections.

test/test_docblock_annotations.rb

@@ -0,0 +1,22 @@
+require File.expand_path('../helper', __FILE__)
+
+class RoccoDocblockAnnotationsTest < Test::Unit::TestCase
+  def test_basics
+    r = Rocco.new( 'test', '', { :language => "c", :docblocks => true } ) { "" } # Generate throwaway instance so I can test `parse`
+    assert_equal(
+      [
+        "Comment\n\n> **param** mixed foo  \n> **return** void  "
+      ],
+      r.docblock( ["Comment\n\n@param mixed foo\n@return void"] )
+    )
+  end
+  def test_highlighted_in_blocks
+    r = Rocco.new( 'test', '', { :language => "c", :docblocks => true } ) { "" } # Generate throwaway instance so I can test `parse`
+    highlighted = r.highlight( r.split( r.parse( "/**\n * Comment\n * @param type name\n */\ndef codeblock\nend\n" ) ) )
+
+    assert_equal(
+      "<p>Comment</p>\n\n<blockquote><p><strong>param</strong> type name</p></blockquote>\n",
+      highlighted[0][0]
+    )
+  end
+end