ocaml/ocaml — pull request #29 by superbobry (2014-04-09 07:14:19+00:00)
Title: PR#4518: change location format for reporting errors in ocamldoc

As requested by @dbuenzli, I've changed ocamldoc location format to:

```
File "src/xmlm.mli", line 3, character 39:
```

However, there's a couple of issues worth discussing:

1. Warnings currently don't have any location information, e.g. the following results in "Warning: Element `some_error` not found".

```ocaml
(** {b Raises {!some_error} on input errors}. *)
```
2. Parse errors might be reported twice. For instance, if we remove the closing bracket in the example above

```ocaml
(** {b Raises {!some_error} on input errors. *)
```

we'll see

```
File "./test.mli", line 0, character 40:
{b Raises {!some_error} on input errors.
^
File "./test.mli", line 0, character 40:
{b Raises {!some_error} on input errors.
^
2 error(s) encountered
```
This happens because the module is processed in two steps:
* First ocamldoc tries to [extract](https://github.com/ocaml/ocaml/blob/trunk/ocamldoc/odoc_comments.mli#L45) the first special comment in the module, returning its `length` for further analysis.
* Then ocamldoc parses all of the remaining special comments, using `length`, obtained in the previous step, as a starting position for parsing.

So, if the first step fails with a parse error, `length` [is assumed](https://github.com/ocaml/ocaml/blob/trunk/ocamldoc/odoc_comments.ml#L42) to be `0`. Thus, the second step starts with the beginning of the file and yields the same parse error.