Skip to content
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

Closed
vicuna opened this issue Dec 15, 2015 · 8 comments
Closed

We need a documentation for compiler warnings and errors #7094

vicuna opened this issue Dec 15, 2015 · 8 comments

Comments

@vicuna
Copy link

vicuna commented Dec 15, 2015

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.

@vicuna
Copy link
Author

vicuna commented Feb 11, 2016

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?
This part would be really empty at this point, but it sounds like a good location to put some future documentations for the relaxed value restriction or even GADTs if they are moved outside of the extension section.

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.

@vicuna
Copy link
Author

vicuna commented Feb 11, 2016

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",
or "Using OCaml" (understand: description of language features
intended for human understanding)
"The OCaml language" into "Language Reference" (understand:
exhaustive description intended for completeness)

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.

@vicuna
Copy link
Author

vicuna commented Feb 11, 2016

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.

@vicuna
Copy link
Author

vicuna commented Feb 11, 2016

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.

@vicuna
Copy link
Author

vicuna commented Feb 12, 2016

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
manual section in #468.

@vicuna
Copy link
Author

vicuna commented Feb 12, 2016

Comment author: @gasche

I created a new git branch to track the progress of the documentation effort:

https://github.com/ocaml/ocaml/tree/warnings-documentation

@vicuna
Copy link
Author

vicuna commented Apr 17, 2016

Comment author: @gasche

I just pushed in this branch an explanation for Warning 52: Fragile constant pattern.

@vicuna
Copy link
Author

vicuna commented Apr 19, 2016

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants