PR#6069: improve ocamldoc error message (bis)

git-svn-id: http://caml.inria.fr/svn/ocaml/trunk@13978 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02

ocamldoc/odoc_lexer.mll

@@ -293,6 +293,10 @@ and elements = parse
         incr Odoc_comments_global.nb_chars;
         print_DEBUG2 "newline";
         elements lexbuf }
+  | "@"
+      {
+        raise (Failure (Odoc_messages.should_escape_at_sign))
+      }
 
   | "@"lowercase+
       {

ocamldoc/odoc_messages.ml

@@ -246,6 +246,7 @@ let file_not_found_in_paths paths name =
     (String.concat "\n" paths)
 
 let tag_not_handled tag = "Tag @"^tag^" not handled by this generator"
+let should_escape_at_sign = "The character @ has a special meaning in ocamldoc comments, for commands such as @raise or @since. If you want to write a single @, you must escape it as \\@."
 let bad_tree = "Incorrect tree structure."
 let not_a_valid_tag s = s^" is not a valid tag."
 let fun_without_param f = "Function "^f^" has no parameter.";;