Haddocking exported instances [was Re: How to disable warning for "export item 'module ...' exports nothing"?]

[Sean Leather]

Isaac Dupree wrote:

> Sean Leather wrote:
>
>> I have a module A that re-exports module B, and module B contains only
>>>
>>>> class
>>>> instances. Since I'm using -Wall, I get this warning about module B
>>>> exporting nothing. Is there a way to disable this particular warning,
>>>> since
>>>> it is unnecessary in this case? No mailing list messages or GHC
>>>> documentation has told me what to do.
>>>>
>>>>  Well, the warning is right that you don't need to re-export module B:
>>> instances are implicitly exported.  So you could just remove the export
>>> of
>>> "module B", unless there's a reason to export it (such as, you might add
>>> some exported functions or data types to it later)
>>>
>>
>>
>> Hmm, the disappointing result of removing module B from the export list is
>> that now it doesn't show up in the Haddock-generated documentation for
>> module A. Not that there was anything specific in B to document, because
>> it's only instances. But I do want the user to know that importing A also
>> imports B. Sigh... I suppose there's CPP if I really want it.
>>
>
So, I tried to do the above with CPP, and I can't get Haddock to recognize
that it should list this. Here's what it looks like:

module A (
  module Z,
#ifdef __HADDOCK__
  module B
#endif
  ) where ...

I added "extensions: CPP" to the .cabal file as I saw instructed in some
Cabal thread from long ago. Building works such that I don't get the
warning, but "cabal haddock" just acts as if it doesn't recognize
__HADDOCK__. Assuming I'm not doing anything wrong, this might be a Cabal
problem.

You could put a link to the module in the intro-documentation that comes
> before the export list, possibly in a sentence saying e.g. "deliberately
> exports instances from @module B@" (except I've forgotten Haddock syntax
> and might have used it wrong there :-)
>

Yep, that is an option. I noticed it in the documentation for another
package, the name of which escapes me right now.

It's an interesting use-case though.  I wonder if Haddock should
> automatically provide links to all instances exported from the module that
> are either (1) instances for datatypes or classes exported by the module, or
> (2) orphan (i.e. not defined in the same module as either the class or the
> datatype).  (It would be too tedious to list *all* exported instances, but
> luckily it's not necessary for completeness.)
>

Yeah, I think instances should be documented in general. But, I agree with
Ross in the previous thread, that's a different story.

Sean
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/glasgow-haskell-users/attachments/20080815/a19c6996/attachment-0001.htm