You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Aug 3, 2024. It is now read-only.
Repository navigation
This repository was archived by the owner on Aug 3, 2024. It is now read-only.
Question: including re-exported module's documentation #958
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
Reacted by Sergey Alirzaev and Vehbi Sinan Tunalioglu
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 #-}
moduleA ( moduleB ) whereimportBmoduleBwhere--| Some docf::Int->Int
f =undefined
This sounds quite doable. Would you like to give it a try @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
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.
Activity
sjakobi commentedon Oct 29, 2018
In principle you could simply replace the re-export of
Bwith the full list ofB's exports. That of course is rather onerous.I think we should probably add an option like
expand-reexported-modulesor so.ivanperez-keera commentedon Oct 29, 2018
Yes, that's what's happening right now here, but I am trying to remove that.
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 commentedon Oct 29, 2018
The logic for not expanding out the full list of re-exports is located here:
haddock/haddock-api/src/Haddock/Interface/Create.hs
Lines 681 to 687 in 2b94a90
The proposed
expand-reexported-modulessounds 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 = undefinedThis sounds quite doable. Would you like to give it a try @ivanperez-keera?
colonelpanic8 commentedon Jun 7, 2019
@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-modulesthat users should have to explicitly opt-in to get this sort of behavior?ivanperez-keera commentedon Jun 9, 2019
I have not done any work on this, no.
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 commentedon Jun 4, 2020
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 commentedon Jun 4, 2020
@l29ah I think you are witnessing a different issue.
If you are referring to the documentation for
getVarScreenInfonot being shown inGraphics.Framebufferbut being shown inGraphics.Framebuffer.Internal, I think the problem is that haddock is somehow interpreting that:accompanies
p'ioctl, notgetVarScreenInfo.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
getVarScreenInfoin the haddock docs, not before (see, for example, http://hackage.haskell.org/package/Yampa-0.13/docs/FRP-Yampa-Conditional.html).l29ah commentedon Jun 4, 2020
Thanks, you're right, and it is #441
brandonchinn178 commentedon May 28, 2024
Bumping this issue. I don't see an explicit motivation mentioned in the thread, so I'll add one here:
jose-jwtlists 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.