Add a way to escape @ at the start of a line.

This should provide an acceptible solution for issues #65, #61, #23.

doclet/src/main/java/ch/raffael/doclets/pegdown/pdrepair/AtSymbolRepair.java

@@ -26,6 +26,17 @@
 
 /**
  * AtSymbolRepair corrects the @ symbol issue, by replacing it with `@`.
+ *
+ * *Demo:* (which will currently fail, unfortunately)
+ *
+ * ```java
+ * @MyAnnotation
+ * public class MyClass {
+ * }
+ * ```
+ *
+ * @see Issue soundso
+ *
  */
 final class AtSymbolRepair extends DefaultMarkdownRepair {
     static final String MARKER = "{-at-}";

doclet/src/main/java/ch/raffael/doclets/pegdown/pdrepair/AtSymbolRepair2.java

@@ -0,0 +1,47 @@
+package ch.raffael.doclets.pegdown.pdrepair;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+
+/**
+ * AtSymbolRepair2 aims to provide a workaround for `@` signs at the beginning of
+ * a line: Prepend an `at` at the start of a line with a `.`. To actually start
+ * the line with `.@`, just add another dot.
+ *
+ * *Demo:*
+ *
+ * ```java
+ * .@MyAnnotation
+ * class MyClass {
+ * }
+ * ```
+ *
+ * And a single dot followed by an at on the beginning of the line:
+ *
+ * ```
+ * .@starts with `.@` in the source
+ * ..@starts with `..@` in the source
+ * ...@starts with `...@` in the source
+ * ```
+ *
+ * @author Raffael Herzog
+ */
+public class AtSymbolRepair2 extends DefaultMarkdownRepair {
+
+    private final Pattern LITERAL_AT = Pattern.compile("([\r\n]\\s*)\\.(\\.*)@");
+    private final String REPLACEMENT = "$1$2{@}";
+
+    @Override
+    public String beforeMarkdownParser(String markup) {
+        StringBuffer buf = new StringBuffer();
+        Matcher matcher = LITERAL_AT.matcher(markup);
+        boolean didMatch = false;
+        while ( matcher.find() ) {
+            matcher.appendReplacement(buf, REPLACEMENT);
+            didMatch = true;
+        }
+        matcher.appendTail(buf);
+        return buf.toString();
+    }
+}

doclet/src/main/java/ch/raffael/doclets/pegdown/pdrepair/MarkdownRepairKit.java

@@ -36,6 +36,7 @@ public MarkdownRepairKit(boolean dropLeadingSpace) {
         final MarkdownRepair spaceCharacterRepair = new SpaceCharacterRepair();
         final MarkdownRepair inlineTagletMarkdownRepair = new InlineTagletRepair();
         final MarkdownRepair atCharacterRepair=new AtSymbolRepair();
+        final MarkdownRepair atCharacterRepair2=new AtSymbolRepair2();
         final MarkdownRepair htmlEntitiesRepair=new HtmlEntitiesRepair();
 
         // before
@@ -44,12 +45,13 @@ public MarkdownRepairKit(boolean dropLeadingSpace) {
         }
 
         before.add(inlineTagletMarkdownRepair);
-        before.add(atCharacterRepair);
+        //before.add(atCharacterRepair);
+        before.add(atCharacterRepair2);
         before.add(htmlEntitiesRepair);
 
         // after
         after.add(htmlEntitiesRepair);
-        after.add(atCharacterRepair);
+        //after.add(atCharacterRepair);
         after.add(inlineTagletMarkdownRepair);
         after.add(spaceCharacterRepair);
     }