Add @doctest as an alias to doctest.

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:

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)

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