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
On 18 October 2012 19:52, Daniel Gorín
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) and didn't have a problem; this is GHC 7.4.2.
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 _______________________________________________ Libraries mailing list Libraries@haskell.org http://www.haskell.org/mailman/listinfo/libraries
-- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com http://IvanMiljenovic.wordpress.com
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). Cheers, Simon
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).
Thanks for your answer. I was using indeed ghc 7.4.1 (and as was pointed out in another mail, one has to replace Right by Left in the example program, sorry about that!). I agree that without orphan instances this is a non-issue, and I'm glad that it was fixed in newer versions of base. Source links for instance definitions would be very handy in general! For orphan instances, it would be a nice feature, perhaps, if haddock could somehow figure out whether an instance is in scope in the module defining the class and/or the type (e.g., by looking for certain paths in the module dependency graph) Then it could mark those instances that are not in scope as orphan and even list the orphan instances defined in a module, which it currently doesn't... Thanks, Daniel
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
participants (4)
-
Brent Yorgey -
Daniel Gorín -
Ivan Lazar Miljenovic -
Simon Hengel