Skip to content
This repository was archived by the owner on Aug 3, 2024. It is now read-only.
This repository was archived by the owner on Aug 3, 2024. It is now read-only.

Question: including re-exported module's documentation #958

Open

Description

@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

Activity

  1. sjakobi commented on Oct 29, 2018

    @sjakobi
    Member

    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.

  2. ivanperez-keera commented on Oct 29, 2018

    @ivanperez-keera
    Author

    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.

  3. harpocrates commented on Oct 29, 2018

    @harpocrates
    Collaborator

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

    lookupExport (IEModuleContents _ (L _ mod_name), _)
    -- only consider exporting a module if we are sure we
    -- are really exporting the whole module and not some
    -- subset. We also look through module aliases here.
    | Just mods <- M.lookup mod_name unrestricted_imp_mods
    , not (null mods)
    = concat <$> traverse (moduleExport thisMod dflags modMap instIfaceMap) mods

    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?

  4. colonelpanic8 commented on Jun 7, 2019

    @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?

  5. ivanperez-keera commented on Jun 9, 2019

    @ivanperez-keera
    Author

    @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.

  6. l29ah commented on Jun 4, 2020

    @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

  7. ivanperez-keera commented on Jun 4, 2020

    @ivanperez-keera
    Author

    @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).

  8. l29ah commented on Jun 4, 2020

    @l29ah

    Thanks, you're right, and it is #441

  9. brandonchinn178 commented on May 28, 2024

    @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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions