[GHC] #10262: Improve documentation of module signatures

[GHC]

#10262: Improve documentation of module signatures
-------------------------------------+-------------------------------------
              Reporter:  goldfire    |             Owner:
                  Type:  bug         |            Status:  new
              Priority:  normal      |         Milestone:
             Component:              |           Version:  7.11
  Documentation                      |  Operating System:  Unknown/Multiple
              Keywords:  backpack    |   Type of failure:  None/Unknown
          Architecture:              |        Blocked By:
  Unknown/Multiple                   |   Related Tickets:
             Test Case:              |
              Blocking:              |
Differential Revisions:              |
-------------------------------------+-------------------------------------
 Out of curiosity, I read the bit in the user manual about the new module
 signatures, and I find the text a little confusing. Could those in the
 know clarify the points below in the manual? Thanks!

 * (typo) The first example refers to `String.hs`. I think you mean
 `Text.hs`.

 * Is there a way to use module signatures to deal with mutually recursive
 modules? The example with `TextSig` seems to require that both `Text` and
 `TextSig` are compiled before `A`.

 * Could you provide an example of specifying multiple
 signature/implementation pairs with `--make`?

 * The manual says that the dialect of Haskell used in signature files is
 "essentially" the same as with hs-boot files. Are there any differences?

 * The most recent paragraph addition doesn't make sense to me, starting
 with "Signatures can be installed like ordinary modules". What do you mean
 by "installed"? What does it mean to bring multiple signatures into scope
 by the same name? Can two signatures have the same name? Wouldn't their
 filenames also need to be the same?

 * Is there currently any facility available to have multiple
 implementations of one signature?

 Of course, this is all work in progress, and I don't necessarily expect an
 immediate fix. But, when it's nearing completion, it may be worth
 revisiting this stretch of text. Thanks!

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