headers
Daniel Gorín | 18 Oct 2012 10:52
Picon
Favicon

haddock, instances and defining modules

Hi

The haddock page for Data.Either lists an instance Functor (Either a). However, this instance doesn't get
in scope when importing Data.Either. E.g., the following program fails to compile:

> import Data.Either
> 
> main = print $ fmap not $ Right "hello"

AFAIK, one needs to import Control.Monad.Instances instead to get such an instance; but there is nothing
in the haddock page of Data.Either that suggests it. This can be quite frustrating for beginners!

It would be good if the docs could be improved here, but I'm not sure what to suggest (maybe haddock should be
generating something else in these cases?)… Any thoughts?

Thanks,
Daniel
Permalink | Reply |
headers
Ivan Lazar Miljenovic | 18 Oct 2012 11:10
Picon
Gravatar

Re: haddock, instances and defining modules

On 18 October 2012 19:52, Daniel Gorín <dgorin <at> dc.uba.ar> wrote:
> Hi
>
> The haddock page for Data.Either lists an instance Functor (Either a). However, this instance doesn't
get in scope when importing Data.Either. E.g., the following program fails to compile:
>
>> import Data.Either
>>
>> main = print $ fmap not $ Right "hello"

Are you sure of this code?

$ghci
GHCi, version 7.4.2: http://www.haskell.org/ghc/  :? for help
Loading package ghc-prim ... linking ... done.
Loading package integer-gmp ... linking ... done.
Loading package base ... linking ... done.
Prelude> fmap not $ Right "hello"

<interactive>:2:18:
    Couldn't match expected type `Bool' with actual type `[Char]'
    In the first argument of `Right', namely `"hello"'
    In the second argument of `($)', namely `Right "hello"'
    In the expression: fmap not $ Right "hello"

>
> AFAIK, one needs to import Control.Monad.Instances instead to get such an instance; but there is nothing
in the haddock page of Data.Either that suggests it. This can be quite frustrating for beginners!

I just started up ghci without importing anything (except the Prelude)
(Continue reading)

Permalink | Reply |
headers
Simon Hengel | 18 Oct 2012 11:32
Gravatar

Re: haddock, instances and defining modules

Hi Daniel,

> The haddock page for Data.Either lists an instance Functor (Either a).
> However, this instance doesn't get in scope when importing
> Data.Either. E.g., the following program fails to compile:
>
> > import Data.Either
> >
> > main = print $ fmap not $ Right "hello"
>
> AFAIK, one needs to import Control.Monad.Instances instead to get such
> an instance; but there is nothing in the haddock page of Data.Either
> that suggests it. This can be quite frustrating for beginners!
>
> It would be good if the docs could be improved here, but I'm not sure
> what to suggest (maybe haddock should be generating something else in
> these cases?)… Any thoughts?

The actual issue is, that the instance definition is orphan (this has
been fixed in base 4.6.0.0).

I think without orphan instances, this problem does not arise.  I'm not
sure whether it's worth the effort to address a problem that only occurs
with orphan instances in Haddock.

It would still be nice if we had "source" links to instance definitions,
and as a side effect they would also address this issue (you could then
simply click on the "source" link to see where that instance is
defined).
(Continue reading)

Permalink | Reply |
headers
Daniel Gorín | 18 Oct 2012 12:21
Picon
Favicon

Re: haddock, instances and defining modules

Hi Simon,

>> The haddock page for Data.Either lists an instance Functor (Either a).
>> However, this instance doesn't get in scope when importing
>> Data.Either. E.g., the following program fails to compile:
>> 
>>> import Data.Either
>>> 
>>> main = print $ fmap not $ Right "hello"
>> 
>> AFAIK, one needs to import Control.Monad.Instances instead to get such
>> an instance; but there is nothing in the haddock page of Data.Either
>> that suggests it. This can be quite frustrating for beginners!
>> 
>> It would be good if the docs could be improved here, but I'm not sure
>> what to suggest (maybe haddock should be generating something else in
>> these cases?)… Any thoughts?
> 
> The actual issue is, that the instance definition is orphan (this has
> been fixed in base 4.6.0.0).
> 
> I think without orphan instances, this problem does not arise.  I'm not
> sure whether it's worth the effort to address a problem that only occurs
> with orphan instances in Haddock.
> 
> It would still be nice if we had "source" links to instance definitions,
> and as a side effect they would also address this issue (you could then
> simply click on the "source" link to see where that instance is
> defined).
(Continue reading)

Permalink | Reply |
headers
Brent Yorgey | 18 Oct 2012 17:00
Favicon
Gravatar

Re: haddock, instances and defining modules

On Thu, Oct 18, 2012 at 11:32:40AM +0200, Simon Hengel wrote:
> 
> It would still be nice if we had "source" links to instance definitions,
> and as a side effect they would also address this issue (you could then
> simply click on the "source" link to see where that instance is
> defined).

+1 for "source" links on instances!  I see there is already a ticket
for this:

  http://trac.haskell.org/haddock/ticket/145

but it is 2 years old.  I guess it just needs someone to actually code
it up.  How hard could it be?

...so I took myself up on my challenge and spent a half-hour source
diving in Haddock to try to figure out what would need to change in
order to support this feature.  I sketched out some notes which I
attached to the above ticket.  Anyone else should feel free to expand
on my notes or actually tackle implementing the feature!

-Brent
Permalink | Reply |

Gmane