[Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? The cannot find documentable link problem also comes up in situations like this (that don't involve type classes): module Ex ( foo ) where data Secret = Secret foo = Secret Should haddock generate documentation for foo (since it is exported) or not (since its result type is not exported)? Now imagine something like instance Show Secret (inside the Ex module). The user of the module then can write show foo, and so it should be documented? J.W. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
On 28 August 2010 21:33, Johannes Waldmann waldm...@imn.htwk-leipzig.de wrote: Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? The cannot find documentable link problem also comes up in situations like this (that don't involve type classes): module Ex ( foo ) where data Secret = Secret foo = Secret Should haddock generate documentation for foo (since it is exported) or not (since its result type is not exported)? The more important question is why doesn't it have a type signature? :p How does GHC deal with that kind of situation? Off the top of my head, I would think that in terms of how you could use it, that would be equivalent to also exporting Secret (the type, not the constructor); i.e. module Ex (Secret, foo) where -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
in terms of how you could use it, that would
be equivalent to also exporting Secret [...]
well, expect that you cannot use the type's name in signatures,
so you'd have to rely on type inference.
Out of curiosity I just checked javadoc's behaviour on
public class Ex {
public interface Show { }
static private class Secret implements Show { }
public Secret foo () { return new Secret (); }
static public class Known implements Show { }
public Known bar () { return new Known (); }
}
and it does generate documentation for all the public identifiers,
with a non-linked result type for foo,
and it does not list Secret among the known instances for Show.
Well, then I checked haddock (2.7.2) for
module Ex ( foo, bar, Known ) where
data Secret = Secret
foo = Secret
instance Show Secret
data Known = Known
bar = Known
instance Show Known
and it behaves identically (does not mention Secret as a known instance).
So, is this the behaviour that the original poster wanted?
J.W.c
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
On Sat, Aug 28, 2010 at 1:41 PM, Ivan Lazar Miljenovic ivan.miljeno...@gmail.com wrote: On 28 August 2010 21:33, Johannes Waldmann waldm...@imn.htwk-leipzig.de wrote: Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? The cannot find documentable link problem also comes up in situations like this (that don't involve type classes): module Ex ( foo ) where data Secret = Secret foo = Secret Should haddock generate documentation for foo (since it is exported) or not (since its result type is not exported)? The more important question is why doesn't it have a type signature? :p How does GHC deal with that kind of situation? Off the top of my head, I would think that in terms of how you could use it, that would be equivalent to also exporting Secret (the type, not the constructor); i.e. module Ex (Secret, foo) where I tried this once, because I was wondering the same thing. Basically it works the way I expected: if you export functions which have a given type in their signature, but the type is not exported, you can use the functions and combine them however you want, but you can't explicitly mention or use the unexported type anywhere. At the time I actually had a use case in mind for why this would be useful, but I can't remember what it was. -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe -- Work is punishment for failing to procrastinate effectively. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
Perhaps Haddock could exclude class instance reporting [...] Instances are global, and cannot be hidden. You cannot prevent their use, so you might as well document them. Otherwise you'll have users complaining when they assume the instance isn't there, and write their own, and then see the error message, but don't find the explanation in the documentation. (rant follows) Yes, globality is bad. - One could wish for (e.g.) let foo :: [Foo] = sort bar where instance Ord Foo where ... Of course this is not Haskell, and that's why there is sortBy etc, where the extra argument corresponds to the dictionary of the type class. Presumably this could be hidden as an implicit parameter, so I guess local instances could be made to work. And local types as well? Sometimes I want them. Heretically speaking, since Java has this (local types), 1. there must be a reason, and 2. there is a way to implement it (well, at least something like it). J.W. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
On 25 August 2010 21:36, Johannes Waldmann waldm...@imn.htwk-leipzig.de wrote: Perhaps Haddock could exclude class instance reporting [...] Instances are global, and cannot be hidden. You cannot prevent their use, so you might as well document them. Yes you can; in that example Alexander linked to before, you can't use the class methods of GraphvizResult; try it, they are: outputCall :: (GraphvizResult o) = o - String isBinary :: (GraphvizResult o) = o - Bool In this case, the class is one defined inside that module and used solely for those two data types; it isn't exported, and the only way you can tell it exists is that Haddock mentions the instances. -- Ivan Lazar Miljenovic ivan.miljeno...@gmail.com IvanMiljenovic.wordpress.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: Documentation of instances with un-documentable type arguments
In this case, the class is one defined inside that module and used solely for those two data types; it isn't exported, and the only way you can tell it exists is that Haddock mentions the instances. OK. I was confused because the text of the posting mentioned MonadReader and MonadState (and their methods set/get/ask/...), which are globally known. J.W. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
