Perhaps there has been some discussion of this, but I could find it after some quick searches here and in GitHub. I would like to float the idea of adding short, explanatory links to compiler error messages and other messages in OCaml platform tools. I think this would be a usability and developer experience win. It could look like this:
utop # 1+();;
Error: This expression has type unit but an expression was expected of type int
š ocaml.org/t/type-error
utop # M.foo ();;
Line 1, characters 0-5:
Alert deprecated: M.foo
Use bar instead
š ocaml.org/t/alert
This could be done not just for compiler messages but for any tools under the OCaml umbrella, including dune and opam.
It would basically be a URL shortener, conceptually similar to golinks or similar shorteners used by companies and people. We would need to maintain a set of mappings from the shortcuts to the expanded urls, e.g.:
The ocaml.org server would have access to these mappings and would redirect from the shortlink to the target link. This level of indirection has the obvious benefit that the redirect targets can be changed and improved over time, while preserving the shortlinks.
I know what youāre thinkingādoing this could potentially require coordinating across two different repos, or doing two discrete actions, whenever any tool wants to include a shortlink in its output. But, I think itās worth it because of the user experience benefits. It would I think also obsolete the need for error message identifier numbers like some other compilers haveāthe shortlinks could uniquely identify each message.
Personally, not a huge fan of having urls in the compiler output: urls feel a little to unweildy ā sure if your terminal supports it, you can click it to quickly open the page, but otherwise youāll have to either copy and paste or remember a long string.
Instead of urls, why not something like a canonical list of error codes that can be quickly searched online (a la rust?).
Wouldnāt a URL be more direct and convenient than a code that you have to search for? Also Iām not proposing just error codes, Iām proposing shortlinks for any tool or purpose. It would be a general-purpose way of linking to appropriate documentation from any non-web tool.
In terms of related upstream work, I guess I should mention my own RFC for Rust-style error identifiers (in the vein of the Haskell error index announced above, although we are not for now trying to suggest that other tools in the ecosystem should follow the same convention), which was created as actionable feedback from an issue report by @mimoo:
As mentioned in a comment there, we were looking for an Outreachy intern to work on this but havenāt yet found a suitable candidate. (implementing this in the compiler requires some familiarity with OCaml). Anyone interested in helping push this forward should feel free to help.
The RFC document itself provides a more precise specification of what @octachron and myself had in mind for the feature, and details about how we would try to implement it in the compiler codebase.
I should note however that there is not (yet?) a strong consensus to move forward with this feature in the RFC discussion (so it is entirely possible that people would decide not to have the feature after a PR is proposed), and that many different opinions have been voiced as to the details of the error identifier structures, with no consensus either (so we may have to iterate with several versions before one is accepted). I guess this is a common aspect of interface changes.
Why not both? So long as the tool output has a known form (in this case that means unique identifiers for all exceptional conditions), then the mapping from ID to URL and thence to a web page can and should be delegated to third-party tooling.
Thanks for the pointer. In terms of the technical implementation details:
We assume a identifier_of_error : error -> Location.error_identifier in each such module,
so the change to report_error would be minimal:ā¦
It should be possible to make this href_of_error : error -> error_href instead?
In terms of specifying where and how to actually search for the error code once you get it from the compiler, that seems to be out of scope of the RFC. I think that is perhaps even more important to pin down, because itās obviously a bad user experience if you get an error code but itās in an obscure and difficult-to-search location.
That is why I focused so heavily on hyperlinks directly, they are a mechanism of sending the user exactly where they need to go, in one shot, without fumbling around in search engines. As to where each shortlink needs to go, that is probably the most tricky part of this whole enterprise. I gave a couple of examples aboveāthe āAlertsā chapter of the Manual for a ādeprecatedā alert message, and the first chapter āThe core languageā for a basic type error. But even here there could be room for argument! There may be better pages for deprecation alerts and type errors that I donāt know of.
Compiling this mapping is a not-insignificant amount of work. Fortunately, it can be done piecemeal before actually changing anything in the compiler.
Itās not clear to me how exactly the user would use this tooling. Would the compiler print a message āGo to this web page, then search for this unique ID thereā? In this case why not just directly give a hyperlink instead of asking the user to jump through hoops?
If there is a one-to-one mapping from error codes to a website with a better explanation, the compiler can emit the error code alone in its output, then editors or other tooling can implement the functionality to make clicking or interacting with the error open the corresponding url (such as adding the message āGo to ocaml.v3.org/errors/<error-code> for more informationā, or via tool tips or otherwise).
This way we get the best of both worlds - compiler output is concise, and not littered with redundant information, and users, if they want to, also have quick and easy ways to open an explanatory web-pages.
OK, but then we rely on every editor/tooling to implement this functionality. But if we treat the shortlink as the unique identifier itself, it doubles as an unambiguous hyperlink directly. Tools donāt need to learn how to interpret the error codes and direct users to the corresponding link.
Regarding the concise outputāI donāt think there is that much difference between a bare error code like tyco007 and my suggestion of ocaml.org/t/tyco007 in terms of verbosity. And in return for a few extra letters we get the benefit of using a technologyāthe hyperlinkāthat is decades old and well understood by many tools already, with no additional work required.
EDIT: the only real leap I am suggesting here is that the OCaml Platform tools commit to using a shortlink system to have a consistent way of directing users to the correct pages where they need to go at each stage of their dev experience. I am suggesting the path ocaml.org/t/..., that is not really set in stone, just a convenient prefix thatās as short as possible. We do need the willpower to say, yes, we will commit to maintaining these shortlinks.
Iām of course in favor of identifiers or shortlinks, but I donāt understand how the problem you point out, which appears to come from a bug in Merlin, would have been solved by identifiers or shortlinks. Can you elaborate?
If we take a step back from the specific circumstance of this exact warning (disabled by default, accidentally enabled by merlin, will be fixed soon), and look at the general case of a user getting a message, the first thing they generally ask is āWhat is this and how do I deal with it?ā
The link I am proposing would take them to a page which explains what the message means and how to deal with it in general terms (again, itās not prescient so it canāt help with this specific merlin issue, explanation links like this must by necessity be general-purpose
