Ghc more detailled missing symbols #1118
Conversation
|
The CI issue seems unrelated to the change I've done. |
|
@harpocrates hello, I'd really like to have feedback on this change, at least know if I have a chance to get it merged or not. |
There was a problem hiding this comment.
This is definitely a useful feature (and, as you observed, will be necessary in conjunction with your other PR). Eventually, I wonder if we'll also want some option to read in the symbols to ignore from a file. The only way to find out is to try it out. 😄
CI on the 8.8 branch should be working again. Do you have bandwidth to rebase? If not, let me know and I can take care of it for you.
The current formatting of the missing link destination does not really help user to understand the reasons of the missing link. To address this, I've changed the formatting in two ways: - the missing link symbol name is now fully qualified. This way you immediately know which haskell module cannot be linked. It is then easier to understand why this module does not have documentation (hidden module or broken documentation). - one line per missing link, that's more readable now that symbol name can be longer due to qualification. For example, before haddock was listing missing symbol such as: ``` could not find link destinations for: Word8 Word16 mapMaybe ``` Now it is listed as: ``` could not find link destinations for: - Data.Word.Word8 - Data.Word.Word16 - Data.Maybe.mapMaybe ```
This argument can be used multiples time. A missing link to a symbol listed by `--ignore-link-symbol` won't trigger "missing link" warning.
harpocrates
force-pushed
the
ghc-more-detailled-missing-symbols
branch
from
c476238
to
72cc1c3
Compare
|
Thank you! |
|
I can't seem to get this option recognized in GHC 9.0.1. Am I missing something? |
That's an haddock option. |
|
@guibou, okay, but when I stick it in |
Haa, I tested, yes you are right. |
|
I opened #1424 to track this discussion. |
This pull request is related to #969, but is independent, and closes #1072.
We are using #969 to force haddock to fail when there is missing link on some ghc symbols. We have this in our CI process to ensure a bit of quality on our haddock documentation.
However, sometimes we cannot directly fix missing links. For example the link may be to an hidden module or some symbols not yet handled by haddock, such as #1070 and #1071.
This pull request changes haddock in a few ways:
Word8, it saysData.Word.Word8.--ignore-link-symbolwhich will ignore a specified missing link. This helps reducing output garbage and will ensure that haddock won't fail once Use the Ghc monad to emit warnings #969 is merged.