Opened 13 months ago

Last modified 11 days ago

#14229 new bug

Contraditions in users_guide/using-warnings.html

Reported by: MikolajKonarski Owned by: voanhduy1512
Priority: low Milestone:
Component: Documentation Version: 8.2.1
Keywords: newcomer Cc:
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: Documentation bug Test Case:
Blocked By: Blocking:
Related Tickets: Differential Rev(s): Phab:D4528, Phab:D4562
Wiki Page:

Description

Lists are not updated in

https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/using-warnings.html

E.g., it says "The warnings that are not enabled by -Wall are...-Wredundant-constraints", but then it says "This option is on by default". Also "-Worphans" is on none of the list of enabled or not enabled flags and also there is no mention in its description if its enabled by default or not. I guess there may be more.

Also, it may be worth mentioning that obsolete warnings or warnings subsumed by others are not on any of the list, or whatever the actual rule is.

Change History (17)

comment:1 Changed 13 months ago by bgamari

Oh dear; yes, it was only a matter of time until this fell out of sync. I'm a bit on the fence regarding whether we should invest some effort into automating the documentation generation or just fix it this once and try to be more careful in the future.

comment:2 Changed 13 months ago by MikolajKonarski

That's actually an easy, nice, introductory ticket for would-be GHC-contributors, so why waste computing power, when humans can do it almost as well. :) We'd just need to post it once a major release on a page with intro tickets and perhaps advertise the page on some hacker forums.

comment:3 Changed 12 months ago by bgamari

Keywords: newcomers added

Indeed we have the newcomers tag for precisely this reason.

comment:4 Changed 6 months ago by voanhduy1512

Hello, I am new to Haskell (never use in prod) and ghc but i think i can help. I need to follow this process https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/DocumentationChanges to update the document right?

comment:5 Changed 6 months ago by voanhduy1512

Differential Rev(s): Phab:D4528
Owner: set to voanhduy1512

comment:6 Changed 6 months ago by Ben Gamari <ben@…>

In c16df60/ghc:

document: fix trac issue #14229

Accroding to
https://git.haskell.org/ghc.git/commitdiff/49672659113371c3bee691e6d913d
f8e6f60a1d8,
`-Wredundant-constraints` is no longer turn on by default.

Reviewers: bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie, carter

Differential Revision: https://phabricator.haskell.org/D4528

comment:7 Changed 6 months ago by bgamari

Thanks voanhduy1512! Have you checked whether any of the other issues brought up in this ticket still need fixing?

comment:8 in reply to:  7 Changed 6 months ago by voanhduy1512

Replying to bgamari:

Thanks voanhduy1512! Have you checked whether any of the other issues brought up in this ticket still need fixing?

I think there are other missing doc, likes no mentions about deferred-type-errors, type-holes ... I will send another patch to address all missing pieces that i can identify.

comment:9 Changed 6 months ago by bgamari

Thanks again for picking this up!

comment:10 Changed 6 months ago by MikolajKonarski

Indeed, thank you, voanhduy1512.

comment:11 in reply to:  9 Changed 6 months ago by voanhduy1512

Replying to bgamari:

Thanks again for picking this up!

Replying to MikolajKonarski:

Indeed, thank you, voanhduy1512.

You are welcome.

I have one more question: currently -Wall written in the form that's list warning that are not enable. But the code itself actually is -W plus few more warnings. So with more warnings add to ghc, the doc will be very easy to be incorrect. Should we change the doc for -Wall to say what it included instead of excluded?

Last edited 6 months ago by voanhduy1512 (previous) (diff)

comment:12 Changed 6 months ago by MikolajKonarski

I'm not sure, because many of the new warnings are added with the intention of adding them to -Wall sooner or later, so the positive list would need to grow, too. Also, the list of warnings included in -Wall is much longer than the list of warnings excluded. An option is to provide both lists and remark that if a warning is on neither list, it must be a new one and please file a Trac ticket. Then we are at least not stating a falsehood.

comment:13 Changed 6 months ago by voanhduy1512

Differential Rev(s): Phab:D4528Phab:D4528, Phab:D4562

comment:14 in reply to:  12 Changed 6 months ago by voanhduy1512

Replying to MikolajKonarski:

I'm not sure, because many of the new warnings are added with the intention of adding them to -Wall sooner or later, so the positive list would need to grow, too. Also, the list of warnings included in -Wall is much longer than the list of warnings excluded. An option is to provide both lists and remark that if a warning is on neither list, it must be a new one and please file a Trac ticket. Then we are at least not stating a falsehood.

I try to build a list status of options here https://gist.github.com/voanhduy1512/7769e04b925069170212400b57f5d4a3. Right now there is more options which excluded in -Wall than included. Maybe it will be change in future but i think it's easier to add positive list.

For example i add a option to -Wall but forgot to update the doc, it's easy to update the doc to correct state just by looking at the code. As for current state, i need to get all options, minus all default options, minus all -W, -Wall, to get the real list that are not in -Wall.

comment:15 Changed 6 months ago by MikolajKonarski

Wow, great job. You are right, I had in mind the total number of warnings included by -Wall, but we list them separately for on, -W and -Wall and that's indeed the best way. I like your idea to provide a positive list for -Wall, as is the case for the other groups. Ben, what do you think?

comment:16 Changed 4 months ago by MikolajKonarski

There is a new comment Phab (I know there were problems with notification emails recently): https://phabricator.haskell.org/D4562#128940

comment:17 Changed 11 days ago by monoidal

Keywords: newcomer added; newcomers removed
Note: See TracTickets for help on using tickets.