Question: including re-exported module's documentation

[ivanperez-keera]

I'm importing and re-exporting several modules:

module A (module B) where
import B

module B where
-- | Some doc
f :: Int -> Int
f = undefined

The documentation for f is not included explicitly in A. If I run it as is, module A's documentation includes a line that says:

module B

but that is all.

AFAIK, there are two ways of making f's documentation included in A: explicit imports and explicit hiding.

Now, in my case, A imports many modules each of which has many functions, so I do not want to have explicit imports listing every definition.

If I hide something from B, then I achieve the effect that I want (the documentation for f is included in module A's documentation), but I want to re-export everything, and the same effect is not achieved if I hide () or (nonexistingdefinition).

Any advice?

EDIT: clarifies explanation; typo

[sjakobi]

In principle you could simply replace the re-export of B with the full list of B's exports. That of course is rather onerous.

I think we should probably add an option like expand-reexported-modules or so.

[ivanperez-keera]

In principle you could simply replace the re-export of B with the full list of B's exports. That of course is rather onerous.

Yes, that's what's happening right now here, but I am trying to remove that.

I think we should probably add an option like expand-reexported-modules or so.

That would be great. If this is not a big feature and someone can guide me a bit, I could try and contribute it.

[harpocrates]

The logic for not expanding out the full list of re-exports is located here:

https://github.com/haskell/haddock/blob/2b94a90a23f03a749e3703af330d9585a5de0bae/haddock-api/src/Haddock/Interface/Create.hs#L681-L687

The proposed expand-reexported-modules sounds great. To be clear, I would expect this to be a module-level option which would dictate what that module does with all re-exported modules (that are imported via unrestricted imports). Something like:

{-# OPTIONS_HADDOCK expand-reexported-modules #-}
module A ( module B ) where
import B

module B where
-- | Some doc
f :: Int -> Int
f = undefined

This sounds quite doable. Would you like to give it a try @ivanperez-keera?

[colonelpanic8]

@sjakobi @ivanperez-keera @harpocrates I take it no one has worked on this?

This is something that I wouldn't mind picking up, but not sure I totally understand the logic for not reexporting.

Is the idea behind expand-reexported-modules that users should have to explicitly opt-in to get this sort of behavior?

[ivanperez-keera]

@sjakobi @ivanperez-keera @harpocrates I take it no one has worked on this?

I have not done any work on this, no.

This is something that I wouldn't mind picking up, but not sure I totally understand the logic for not reexporting.

Is the idea behind expand-reexported-modules that users should have to explicitly opt-in to get this sort of behavior?

That would be my understanding of this flag, yes. Based on what @harpocrates suggests, this would be like a flag that you enable on a module with:

{-# OPTIONS_HADDOCK expand-reexported-modules #-}

and would make that module's documentation include everything that any exported modules export.

[l29ah]

In principle you could simply replace the re-export of B with the full list of B's exports.

Even this won't do the job. The re-exported functions will lack the documentation generated from comments. See https://hackage.haskell.org/package/linux-framebuffer for an example

[ivanperez-keera]

@l29ah I think you are witnessing a different issue.

If you are referring to the documentation for getVarScreenInfo not being shown in Graphics.Framebuffer but being shown in Graphics.Framebuffer.Internal, I think the problem is that haddock is somehow interpreting that:

-- | Asks the properties of the supplied framebuffer device

accompanies p'ioctl, not getVarScreenInfo.

Looking at https://hackage.haskell.org/package/linux-framebuffer-0/docs/Graphics-Framebuffer-Internal.html#v:p-39-ioctl I would expect the documentation to be shown after getVarScreenInfo in the haddock docs, not before (see, for example, http://hackage.haskell.org/package/Yampa-0.13/docs/FRP-Yampa-Conditional.html).

[l29ah]

Thanks, you're right, and it is https://github.com/haskell/haddock/issues/441

[brandonchinn178]

Bumping this issue. I don't see an explicit motivation mentioned in the thread, so I'll add one here: jose-jwt lists Jose.Types in other-modules, so its haddocks arent generated. Jose.Jwt reexports the full Jose.Types module, but because it's an internal module, there's no reference to the types in that module in the haddocks, making it seem like they're not exported at all.