[GHC] #10140: Suggestions for improvement of the Safe Haskell chapter in the user's guide

[GHC]

#10140: Suggestions for improvement of the Safe Haskell chapter in the user's guide
-------------------------------------+-------------------------------------
              Reporter:  thomie      |             Owner:
                  Type:  bug         |            Status:  new
              Priority:  normal      |         Milestone:
             Component:              |           Version:  7.8.4
  Documentation                      |  Operating System:  Unknown/Multiple
              Keywords:              |   Type of failure:  None/Unknown
          Architecture:              |        Blocked By:
  Unknown/Multiple                   |   Related Tickets:
             Test Case:              |
              Blocking:              |
Differential Revisions:              |
-------------------------------------+-------------------------------------
 I've been reading the
 [http://haskell.inf.elte.hu/docs/7.11.20150306.noWin32/html/users_guide
 /safe-haskell.html documentation] on Safe Haskell. Cool stuff. Here are
 some suggestions for improvement, I hope some are useful:

 * 7.29.1.2
 This comment is the first introduction to the pragmas `TrustWorthy` and
 `Safe`:
 {{{
 -- Either of the following Safe Haskell pragmas would do
         {-# LANGUAGE Trustworthy #-}
         {-# LANGUAGE Safe #-}
 module RIO ...
 }}}
 Why is either allowed? I suspect because of the details of this module,
 but this is not explicitly stated. Furthermore, later it is said that
 `-XTrustworthy` should be used, not `-XSafe`:
   "This is done by compiling the RIO module with the -XTrustworthy flag
 and compiling the Danger module with the -XSafe flag."

 * 7.29.2

   "TemplateHaskell — Is particularly dangerous, as it can cause side
 effects even at compilation time"

 One could now think that `Safe Haskell` does guarantee compilation safety.
 Since that is not the case, I would remove that sentence (things are
 explained properly in the Safe Compilation section).

 * 7.29.2

   "Hand crafted instances of the Typeable type class are not allowed in
 Safe Haskell".

 Make a mention of the
 [https://downloads.haskell.org/~ghc/7.8.4/docs/html/users_guide/deriving.html
 following]:

   "... since GHC 7.8.1, handwritten (ie. not derived) instances of
 Typeable are forbidden, and will result in an error."

 * 7.29.4

 After listing `-XSafe`, `-XTrustWorthy`, `-XUnsafe`:

   "The procedure to check if a module is trusted or not depends on if the
 -fpackage-trust flag is present. The check is very similar in both cases"

 There are three cases.


 * 7.29.4.1. Trust check (-fpackage-trust disabled)

   "A module M in a package P is trusted by a client C if and only if:

   Both of these hold:

     1. The module was compiled with -XSafe

     2. All of M's direct imports are trusted by C"

 But isn't the latter implied by the former, or the module wouldn't
 compile? If that is correct, please mention it. Same in the next section
 (7.29.4.2).

 * 7.29.4.2

   "Having the -fpackage-trust flag also nicely unifies the semantics of
 how Safe Haskell works when used explicitly and how modules are inferred
 as safe."

 Should explicitly be implicitly? I don't understand this sentence
 regardless. What does nicely unifies mean?

 * 7.29.4.1 and 7.29.4.2

 There is no mention of Safe Haskell Inference in these rules, only "The
 module was compiled with -XSafe" and "The module was compiled with
 -XTrustWorthy". I think the following statement should be true, but I'm
 not sure: "If a module M in a package P is inferred to be Safe by GHC,
 then it is trusted by client C".

 Actually, there is only a short mention of safe inference in the
 introduction, whereas I suspect it should be mentioned everywhere where
 `-XSafe` is.

 * 7.29.5

   "That is, the use cases outlined and the purpose for which Safe Haskell
 is intended: compiling untrusted code."

 Before, "compiling and executing untrusted code" was listed as one of two
 cases. Now it's mentioned as the single purpose. Minor issue.

 * 7.29.5

   "Say you are writing a Haskell library. Then you probably just want to
 use Safe inference."

 I have more of a general question about this: if this is true, then why
 are there over 200 mentions of `{-# Language Safe #-}` in a checkout of
 ghc?

 Is it because 'Safe Haskell Inference' was not added to GHC until version
 7.4 (is that true? I inferred it from the difference between the 7.2 and
 7.4 user's guides). So maybe modules that need to be compileable with
 earlier versions of GHC have to specify -XSafe explicitly? Some guidance
 on this would be helpful.

 * There are 2 `ulink`s that don't work. Should be `xref`.

--
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/10140>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler