From 4a01942b131d87ca2cb59aca1583e525727afa8f Mon Sep 17 00:00:00 2001
From: Jakukyo Friel <weakish@gmail.com>
Date: Tue, 25 Nov 2014 05:27:05 +0800
Subject: [PATCH] Add @doctest as an alias to doctest.

Now the following test code works:

For compatibility with YARD, @doctest allows indentations, while
does not allow multiline test description.
---
 doc/special_directives.doctest |  6 +++++-
 lib/runner.rb                  | 24 +++++++++++++++++++++++-
 lib/special_directive.rb       |  7 ++++++-
 3 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/doc/special_directives.doctest b/doc/special_directives.doctest
index 40a1b0d..eeb5729 100644
--- a/doc/special_directives.doctest
+++ b/doc/special_directives.doctest
@@ -12,10 +12,14 @@ This directive splits your irb sessions into logical "test units" with descripti
 
 	doctest: This is the first test.  Is this document up to date with the code?
 	>> RubyDocTest::SpecialDirective::NAMES
-	=> ["doctest:", "it:", "!!!", "doctest_require:"]
+	=> ["doctest:", "@doctest", "it:", "!!!", "doctest_require:"]
 
 Any irb sessions appearing before the first doctest: directive will be included in an all-encompassing "Default Test".  If you have no "doctest:" directives anywhere in your document, then all irb statements will be placed in the "Default Test".
 
+For compatibility with YARD, we provide `@doctest`, which is an alias for `doctest:`.
+Note that `@doctest` does not support multi-line test description,
+for compatibility with YARD.
+
 ### The "!!!" Directive
 
 This directive opens an interactive ruby session (irb), in context, so you can play around with the variables.  If you run this document, you will be prompted at the following line:
diff --git a/lib/runner.rb b/lib/runner.rb
index 2c20cb9..af8381f 100644
--- a/lib/runner.rb
+++ b/lib/runner.rb
@@ -310,7 +310,7 @@ def organize_blocks(groups = @groups)
           current_statements = []
         when SpecialDirective
           case g.name
-          when "doctest:", "it:"
+          when "doctest:", "@doctest", "it:"
             blocks << CodeBlock.new(current_statements) unless current_statements.empty?
             current_statements = []
             blocks << g
@@ -376,6 +376,25 @@ def require_relative_to_file_name(file_name, relative_to)
     # >> r.tests.first.code_blocks.size
     # => 2
     #
+    # doctest: "@doctest" is an alias to "doctest:"
+    # >> r = RubyDocTest::Runner.new("@doctest This is an alias.\n  >> t = 1\n  >> t + 2\n  => 3\n  >> u = 1", "test.doctest")
+    # For compatibility with YARD, tests are indented.
+    # >> r.prepare_tests
+    # >> r.tests.size
+    # => 1
+    #
+    # >> r.tests.first.description
+    # => "This is an alias."
+    #
+    # >> r.tests.first.code_blocks.size
+    # => 2
+    #
+    # @doctest "@doctest" does not support multi-line description.
+    # >> r = RubyDocTest::Runner.new("@doctest line 1\n  line 2\n>> t = 1\n=> 1", "test.doctest")
+    # >> r.prepare_tests
+    # >> r.tests.first.description
+    # => 'line 1'
+    #
     # doctest: When using the "it:" directive, it should re-append "it" to the description;
     # >> r = RubyDocTest::Runner.new("it: should behave\n>> t = 1\n>> t + 2\n=> 3\n>> u = 1", "test.doctest")
     # >> r.prepare_tests
@@ -400,6 +419,9 @@ def organize_tests(blocks = @blocks)
           when "doctest:"
             assigned_blocks = []
             tests << Test.new(g.value, assigned_blocks)
+          when "@doctest"
+            assigned_blocks = []
+            tests << Test.new(g.value.split("\n").first, assigned_blocks)
           when "it:"
             assigned_blocks = []
             tests << Test.new("it #{g.value}", assigned_blocks)
diff --git a/lib/special_directive.rb b/lib/special_directive.rb
index a974f0e..c62e216 100644
--- a/lib/special_directive.rb
+++ b/lib/special_directive.rb
@@ -5,7 +5,7 @@
 
 module RubyDocTest
   class SpecialDirective < Lines
-    NAMES = ["doctest:", "it:", "!!!", "doctest_require:"]
+    NAMES = ["doctest:", "@doctest", "it:", "!!!", "doctest_require:"]
     NAMES_FOR_RX = NAMES.map{ |n| Regexp.escape(n) }.join("|")
     
     # === Test
@@ -15,6 +15,11 @@ class SpecialDirective < Lines
     # >> s.name
     # => "doctest:"
     #
+    # doctest: "@doctest" is a valid directive
+    # >> s = RubyDocTest::SpecialDirective.new(["@doctest is an alias."])
+    # >> s.name
+    # => "@doctest"
+    #
     # doctest: "it:" is a valid directive
     # >> s = RubyDocTest::SpecialDirective.new(["it: should test stuff"])
     # >> s.name