Original bug ID: 6069
Just stumbled upon the case when ocamldoc aborts with unhelpful error message. Consider :
$ cat q.ml
1 error(s) encountered
In the real code it is hard to figure out what line causes an error. It appears all the code to track line numbers is in place, but not used when reporting errors. Simple patch below.
diff --git a/ocamldoc/odoc_comments.ml b/ocamldoc/odoc_comments.ml
The text was updated successfully, but these errors were encountered:
Comment author: @gasche
There are several different things in this patch:
I think (1) could be done better, but that would require more effort. The patch format is an improvement over the previous format, but it does not respect the usual OCaml convention (so no emacs location parsing for example), and in particular it does not report character positions. The nice way to fix that would be to call "Location.curr lexbuf" at error points inside the lexer (as done in the usual OCaml parser), or at least when catching the Failure exception in odoc_comments.ml (but then you need to change this code so that you know which "lexbuf" value provoked the error).
I'd say (2) can be easily improved: instead of turning @foo+ into @foo* and then raise an error on the empty foo* case, why not just handle @ alone specifically? That would be more readable. It seems to me that the longest-match precedence rule of lexers should make that work nicely.
I'm not sure I understand (3). Why does it say "in @-tags arguments"? I didn't know about the problem before reading your patch, but I'd say that there is an error for any isolated @ in the comment, not only after, say, a @raise keyword (which expects arguments). Besides, it would be helpful if the error message mentioned explicitly mentioned how to escape (rather than just the need for an escape). I would suggest something like "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 @.".
(Do we really need to fail when we read @ followed by something else than a lowercase ? I think it is prudent to do so, as it leaves the door open to extending the lexical structure of @-commands in the future.)
Comment author: hnrgrgr
Well, my intention was just to track down the error. Hence, fixing point (2) was my sole intention. To improve readability, I've updated this part of the patch as suggested.
For point (3), I tried to be coherent with the ocamldoc manual:
As said in the manual, there is not an error for every isolated @-sign, it appears only after the first @-tags. Still, one may probably improve the error message.
I remove point (1) from the modified patch.
Comment author: @gasche
I'm not sure I understand the same thing from the documentation. If
Then my understanding is that the first non-escaped '@', followed by