[commit: ghc] wip/D4333: [WIP] Hi Haddock: Enable haddock to generate docs from .hi-files (5a6ea93)

Mon Jan 21 01:33:56 UTC 2019

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/D4333
Link       : http://ghc.haskell.org/trac/ghc/changeset/5a6ea938949d01e35b280c3bf06c83f0d690922c/ghc

>---------------------------------------------------------------

commit 5a6ea938949d01e35b280c3bf06c83f0d690922c
Author: Simon Jakobi <simon.jakobi at gmail.com>
Date:   Sun Jan 20 20:24:32 2019 -0500

    [WIP] Hi Haddock: Enable haddock to generate docs from .hi-files

    Summary:
    This extends my work from D4758 and enables haddock to generate docs
    from information enclosed in the `.hi` interface files.

    ## Main changes

    * `HaddockLex` contains an Alex-based lexer for docstrings that detects
      identifiers delimited with `'` or backticks.

    * `HsDoc.Docs` comprises the `DeclDocMap` and `ArcDocMap` structures added in D4758 and
      other data needed by haddock.

    * haddock now uses `GhcMake.load'` to load `.hi`-files, hooking into GHC's recompilation
      avoidance. In order to avoid recompilation when a `.hi`-file already contains documentation
      we use a new option `Opt_SkipIfaceVersionCheck`.

    ## TODOs and requests for comment

    * [ ] Work out a specification for a deterministic module structure (`docs_structure`) and
          update the existing code to implement it. The `HaddockIssue849` test case is currently flaky
          because the ordering of constructors in the `Avail` for `Maybe` fluctuates.
          See [haddock#956](https://github.com/haskell/haddock/issues/956).

    * [ ] Possibly fuse `mi_exports` and `docs_structure`. Currently both serialize the same `Avails`.
        Also discussed at [haddock#956](https://github.com/haskell/haddock/issues/956).

    * [ ] Get the recompilation avoidance right: While some of the checks performed in `checkVersions`
          are irrelevant for haddock, we may want to keep some of them.
          We probably also want `-haddock` to cause recompilation if an existing `.hi`-file
          doesn't contain the `Docs`.

    * [ ] Fix the tests. `./validate` currently reports failures for
          `TEST="HaddockIssue849 ImpSafeOnly01 ImpSafeOnly02 ImpSafeOnly03 ImpSafeOnly04 ImpSafeOnly05 ImpSafeOnly06 ImpSafeOnly07 ImpSafeOnly08 ImpSafeOnly09 ImpSafeOnly10 Splices T13168 T14304 T4029 T9881 break006 break011 break013 break024 cabal01 dynamicToo002 dynamicToo005 haddock.base haddock.compiler hist001 hist002 plugins09 plugins11 print026 safePkg01"`

    * [ ] Serialize instance locations. Discussed at [haddock#921](https://github.com/haskell/haddock/issues/921).

    Several more (minor) issues are marked `TODO` in the source code.

    ---

    The corresponding changes in haddock are [here](https://github.com/haskell/haddock/pull/906).

    ## Possible further work

    * Add an option to configure the identifier delimiters the lexer looks for.
    * Add an option to make the lexer exclude birdtracks.
    * Make the `:doc` command also pretty-print arg docs.

    Reviewers: bgamari, alanz, harpocrates, alexbiehl, hvr

    Subscribers: Tritlo, Fuuzetsu, thomie, rwbarton, mpickering, carter, wz1000, harpocrates, gershomb, hvr, alexbiehl

    GHC Trac Issues: #15786

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

>---------------------------------------------------------------

5a6ea938949d01e35b280c3bf06c83f0d690922c
 compiler/basicTypes/BasicTypes.hs                  | 102 +++---
 compiler/deSugar/Desugar.hs                        |   6 +-
 compiler/deSugar/ExtractDocs.hs                    | 237 +++++++++---
 compiler/ghc.cabal.in                              |   1 +
 compiler/hieFile/HieAst.hs                         |   2 +-
 compiler/hsSyn/HsDecls.hs                          |  37 +-
 compiler/hsSyn/HsDoc.hs                            | 404 +++++++++++++++++----
 compiler/hsSyn/HsImpExp.hs                         |  12 +-
 compiler/hsSyn/HsSyn.hs                            |   6 +-
 compiler/hsSyn/HsTypes.hs                          |   4 +-
 compiler/iface/LoadIface.hs                        |  25 +-
 compiler/iface/MkIface.hs                          |  45 +--
 compiler/main/DynFlags.hs                          |   9 +
 compiler/main/GHC.hs                               |   2 +-
 compiler/main/HeaderInfo.hs                        |   1 +
 compiler/main/HscTypes.hs                          |  84 +++--
 compiler/main/InteractiveEval.hs                   |  29 +-
 compiler/parser/HaddockLex.x                       | 146 ++++++++
 compiler/parser/HaddockUtils.hs                    |  10 +-
 compiler/parser/Parser.y                           |  62 +++-
 compiler/parser/RdrHsSyn.hs                        |  15 +-
 compiler/rename/RnEnv.hs                           |  15 +-
 compiler/rename/RnHsDoc.hs                         |  51 ++-
 compiler/rename/RnNames.hs                         |  22 +-
 compiler/rename/RnSource.hs                        |   7 +-
 compiler/typecheck/TcHoleErrors.hs                 |  53 ++-
 compiler/typecheck/TcRnDriver.hs                   |  18 +-
 compiler/typecheck/TcRnTypes.hs                    |   4 +-
 compiler/utils/Binary.hs                           |  82 ++++-
 compiler/utils/Encoding.hs                         |  61 +++-
 compiler/utils/EnumSet.hs                          |  35 ++
 compiler/utils/Outputable.hs                       |   5 +
 ghc/GHCi/UI.hs                                     |   4 +-
 libraries/base/Data/Function.hs                    |   2 +
 libraries/base/GHC/Exts.hs                         |   1 +
 libraries/ghc-prim/GHC/Magic.hs                    |   1 +
 libraries/ghc-prim/GHC/Types.hs                    |   1 +
 .../tests/ghc-api/annotations/stringSource.hs      |  15 +-
 .../plugins/simple-plugin/Simple/SourcePlugin.hs   |   1 +
 testsuite/tests/showIface/DocsInHiFile.hs          |  11 +-
 testsuite/tests/showIface/DocsInHiFile0.stdout     |   5 +-
 testsuite/tests/showIface/DocsInHiFile1.stdout     | 143 ++++++--
 testsuite/tests/showIface/HaddockIssue849.hs       |  10 +
 testsuite/tests/showIface/HaddockIssue849.stdout   |  32 ++
 testsuite/tests/showIface/HaddockOpts.hs           |   2 +
 testsuite/tests/showIface/HaddockOpts.stdout       |  24 ++
 testsuite/tests/showIface/Inner0.hs                |   3 +
 testsuite/tests/showIface/Inner1.hs                |   4 +
 testsuite/tests/showIface/Inner2.hs                |   3 +
 testsuite/tests/showIface/Inner3.hs                |   3 +
 testsuite/tests/showIface/Inner4.hs                |   4 +
 testsuite/tests/showIface/LanguageExts.hs          |   4 +
 testsuite/tests/showIface/LanguageExts.stdout      |  21 ++
 testsuite/tests/showIface/MagicHashInHaddocks.hs   |   9 +
 .../tests/showIface/MagicHashInHaddocks.stdout     |  33 ++
 testsuite/tests/showIface/Makefile                 |  32 +-
 testsuite/tests/showIface/NoExportList.hs          |  28 ++
 testsuite/tests/showIface/NoExportList.stdout      |  59 +++
 testsuite/tests/showIface/PragmaDocs.hs            |   9 +
 testsuite/tests/showIface/PragmaDocs.stdout        |  34 ++
 testsuite/tests/showIface/ReExports.hs             |  12 +
 testsuite/tests/showIface/ReExports.stdout         |  31 ++
 testsuite/tests/showIface/all.T                    |  28 ++
 utils/genprimopcode/Main.hs                        |   1 +
 64 files changed, 1714 insertions(+), 448 deletions(-)

Diff suppressed because of size. To see it, use:

    git diff-tree --root --patch-with-stat --no-color --find-copies-harder --ignore-space-at-eol --cc 5a6ea938949d01e35b280c3bf06c83f0d690922c