New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
We need a documentation for compiler warnings and errors #7094
Comments
Comment author: @Octachron Concerning the location of this warning documentation, I wonder if it really fits in the already existing parts of the manual: The best location might be at the end of the "Introduction" part but having a detailed list of warnings and compiler errors in the introduction does not feel completely right. Both the language and tools parts are also not really adapted to this documentation. Maybe, it would be better to add a new part to the manual entitled "Advanced guide to OCaml" (or something like that) just after the tutorial part? A possible compromise might be to add an advanced section to the introduction part, and separate it from the introduction once the section reaches a sufficient size. |
Comment author: @gasche Those who do the work decide; given that you are the person that improved the documentation the most recently, I would personally support what you think is best. I think Damien could be interested in giving a second opinion (but he may be a bit too busy with the release preparation right now). That said, for the specific need of having a section dedicated to discussing warnings and errors, I think that your proposal is a bit overkill. I would be happy to have something inside Part III, either at the same place as the current section 8.4 (Common errors, http://caml.inria.fr/pub/docs/manual-ocaml/comp.html#s%3Acomp-errors ), or as its own chapter after the "batch compilation" or "native compilation" chapter. For the change that you propose, another valid option would be to rename: "Introduction to OCaml" into "Presentation of the OCaml language", and add stuff on GADTs, the relaxed value restriction or other language Extensions into the first part. A discussion of compiler errors and warnings could be either in this extended Part I or in Part III. I personally think that Part III is fine for this -- it is still about tooling, although warnings are directed by language usage choices. |
Comment author: @Octachron You are right, my proposition was overkill for this specific need; and simply renaming the "Introduction" part in case of further extensions sounds like a good idea. After some thoughts, I would tend to add a new section "Compiler warning reference" after 8.4 in part III and put only extended description here ? repeating the compiler generated list of warnings does not sounds very readable nor useful. |
Comment author: @gasche Indeed, we would not need to discuss all warnings. What I feel a need for is a place for a rationale of warning choices. Why did we add this warning, what is potentially wrong with the code being warned about, how to recognize false positives, the justification for (not) making it a default warning, etc. If there is nothing more to say than -warn-help for a particular warning, we don't need to list it. |
Comment author: @Octachron Describing in detail all non-obvious warnings and the motivation behind them seems like an laudable goal. To start with a little less ambitious goal, I have extracted the comment on warning 57 in parmatch.ml and transfered to this new |
Comment author: @gasche I created a new git branch to track the progress of the documentation effort: |
Comment author: @gasche I just pushed in this branch an explanation for Warning 52: Fragile constant pattern. |
Comment author: @gasche The warning-documentations branch has been merged in 4.03 and trunk. I'm leaving this as "suspended", rather than "fixed", as I expect the set of documented warnings to grow over time. Anyone, please free to comment here to suggest other warnings that are delicate to understand and correct, we should add them to the documentation. |
Original bug ID: 7094
Reporter: @gasche
Assigned to: @gasche
Status: resolved (set by @gasche on 2016-04-19T16:17:30Z)
Resolution: suspended
Priority: normal
Severity: text
Target version: 4.03.1+dev
Fixed in version: 4.03.0+dev / +beta1
Category: documentation
Monitored by: @hcarty
Bug description
There is currently no documentation of compiler warnings and errors. The best we have is $(ocamlc -warn-help), and
http://caml.inria.fr/pub/docs/manual-ocaml/comp.html#sec251
which lists the -warn-help output. This is not enough as it does not list compiler errors (only a handful of them are listed as "Common errors" in a section below on the same page) and because this is probably not the right place to give longer explanations for warnings.
Additional information
The motivation for this PR is that people requested that the warning text for the new warning 57 (ambiguous pattern variables used in guard) be made shorter, see #317 . The idea was to keep a short warning text, and redirect users for the documentation to actually understand the warning (which takes a bit more explaining than some others), but there is actually no good place for this documentation!
After discussing the matter with Damien, I decided to set the target for 4.03. It is not very hard (and external contributions to do so are warmly welcome) to just take the current
-warn-help
output and put it in a dedicated section of the manual (we can discuss where exactly), and add more content only on warnings that need clarification (typically warning 57, but we have the text written in the GPRs and in code comments). So this should be fixable in time for the 4.03 release.The text was updated successfully, but these errors were encountered: