improve documentation of :doc and -haddock
I was preaching about :doc
but people said "what? does not work here".
Of course it works for me since I have ghc option -haddock
in my global cabal config since forever.
ghci
does the right thing (it prints Try re-compiling with '-haddock'.
) but GHC documantation feels incomplete:
-
documentation for
-haddock
says what is happening (parse Haddock comments and include them in the interface file) but does not say why I should want this https://downloads.haskell.org/ghc/latest/docs/users_guide/using.html#ghc-flag--haddock -
documentation for
:doc
does not say that it needs these interface files, and sounds vague and dated ("experimental, might change with GHC 8.8") https://downloads.haskell.org/ghc/latest/docs/users_guide/ghci.html#ghci-cmd-:doc
(for context, https://club.tidalcycles.org/t/where-are-n-and-notes-documented/5109/8 )
... Can we just make -haddock
the default in ghc? (I am not sure about implications - interface size and compile time might go up). Global -haddock
was a bit risky before GHC version 9 (?) since it would occasionally refuse to generate code when a haddock comment was malformed. But I've never seen such an error recently.