diff --git a/bin/rocco b/bin/rocco index a56c0d3..6468a20 100755 --- a/bin/rocco +++ b/bin/rocco @@ -8,6 +8,7 @@ #/ The string to recognize as a comment marker #/ -o, --output= Directory where generated HTML files are written #/ -t, --template= 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 diff --git a/lib/rocco.rb b/lib/rocco.rb index 5cd3614..fefcfbb 100644 --- a/lib/rocco.rb +++ b/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. diff --git a/test/test_docblock_annotations.rb b/test/test_docblock_annotations.rb new file mode 100644 index 0000000..5fb05a6 --- /dev/null +++ b/test/test_docblock_annotations.rb @@ -0,0 +1,13 @@ +require File.expand_path('../helper', __FILE__) + +class RoccoDocblockAnnotationsTest < Test::Unit::TestCase + def test_docblock_annotation_conversion + 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 +end