ITADN

Documentation lost for identifiers re-exported through more than one hop across internal sub-libraries

#12212Opennikita-volkov 创建于 15 天前
type: bugcabal-install: cmd/haddockre: internal library
N
nikita-volkovcommented
I ran into this with "hasql". In the [published haddock](https://hackage-content.haskell.org/package/hasql-2.0.0.1/docs/Hasql-Encoders.html) your can see that there's no documentation on any definition. However in the [source tree](https://github.com/nikita-volkov/hasql/blob/v2.0.0.1/src/codecs/Hasql/Codecs/Encoders/Value.hs) you will find that in fact the definitions are documented. Following is the description filled according to your template with the help of LLM. **Describe the bug** When a package's main library re-exports an identifier from an internal sub-library, and that identifier is reached through a re-export chain of more than one hop (i.e. it's declared in module A, re-exported by an intermediate module B in the same sub-library, and the main library imports it from B rather than from A directly), `cabal haddock --haddock-for-hackage` silently drops the identifier's documentation - the generated page shows no doc text for it and no build warning is emitted. Identifiers that are imported by the main library directly from the module where they're declared (a single hop) render correctly, even when that declaring module lives in a different internal sub-library. Only the two-hop case loses its docs. **To Reproduce** Steps to reproduce the behavior: ``` $ cabal haddock lib:<mainlib> --haddock-for-hackage ``` With a package shaped like this: ```cabal cabal-version: 3.0 name: repro version: 0.1.0.0 library internal hs-source-dirs: src/internal exposed-modules: Internal.Leaf Internal.Aggregate build-depends: base library hs-source-dirs: src exposed-modules: Public build-depends: base, repro:internal ``` ```haskell -- src/internal/Internal/Leaf.hs module Internal.Leaf where -- | Docs for foo. foo :: Int foo = 1 ``` ```haskell -- src/internal/Internal/Aggregate.hs module Internal.Aggregate (module Internal.Leaf) where import Internal.Leaf ``` ```haskell -- src/Public.hs module Public (foo) where import Internal.Aggregate (foo) ``` After `cabal haddock --haddock-for-hackage`, `foo`'s doc ("Docs for foo.") is missing from `Public`'s Haddock page even though it's present verbatim on `Internal.Leaf`. Changing `Public.hs` to `import Internal.Leaf (foo)` (a single hop straight to the declaration site) makes the doc appear correctly. **Expected behavior** Documentation should be found and rendered for a re-exported identifier regardless of how many re-export hops separate the main library's import from the identifier's declaration site, as long as each hop is a valid, unambiguous re-export. **System information** - Operating system: macOS 26.4 (Darwin 25.4.0, arm64) - `cabal-install` 3.16.1.0 (compiled using version 3.16.1.0 of the Cabal library, in-tree) - `ghc` 9.12.4 **Additional context** This may be related to (or a variant of) https://github.com/haskell/cabal/issues/11475 ("Internal library .haddock path mismatch in `cabal haddock --haddock-all`"), which is about `cabal`'s inability to locate an internal sub-library's `.haddock` interface file at all. In our case the interface file discovery for the sub-library itself does not appear to be the issue - single-hop re-exports from the very same sub-library resolve their docs correctly - so this looks like it could be a separate bug specifically in how Haddock (or cabal's invocation of it) walks re-export chains more than one level deep, rather than a path-construction bug. We have not dug further into root-causing this beyond confirming the hop-count correlation described above; happy to provide the full `hasql` repro if useful, though we haven't yet distilled it into a minimal standalone project.
1 条评论