Haddock: Documentation of instances with un-documentable type arguments

Alexander McPhail

25 Aug 2010 25 Aug '10

6:59 a.m.

Hi, Here, http://hackage.haskell.org/packages/archive/graphviz/2999.10.0.1/doc/html/Da..., there is an example of the internal implementation leaking. I was taught to separate interface from implementation. For example, header versus c/cc/cpp files. The privacy of typeclasses of GeneralNewTypedDeriving'ed variety, such as MonadReader and MonadState, should be hidable. I may want the programmer to know my operations, as provided in the interface, are monadic (and thus sequencable, temporally deterministic operations) but not allow them to set/get, ask, tell, fetch, push, throw, or pass my implementational details. Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? Vivian -- --- yolar et elver. --- DISCLAIMER This transmission contains information that may be confidential. It is intended for the named addressee only. Unless you are the named addressee you may not copy or use it or disclose it to anyone else.

Attachments:

attachment.html (text/html — 1.2 KB)

Show replies by date

Johannes Waldmann

25 Aug 25 Aug

7:36 a.m.

New subject: 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.

Ivan Lazar Miljenovic

8:06 a.m.

On 25 August 2010 21:36, Johannes Waldmann 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.Miljenovic@gmail.com IvanMiljenovic.wordpress.com

Johannes Waldmann

8:32 a.m.

New subject: 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.

David Waern

10:20 a.m.

2010/8/25 Alexander McPhail :

...

Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter?

Yes, it should. BTW, we have a trac ticket for it: http://trac.haskell.org/haddock/ticket/37 You can add yourself to the CC list to show that you want this feature. Currently we don't have many people working on these types of tickets in Haddock (I'm mostly fixing bugs, others are working on bigger improvements), so if more people would volunteer to help out, that'd be great. The mailing list haddock@projects.haskell.org can be used to ask for directions and help. David

Johannes Waldmann

28 Aug 28 Aug

7:33 a.m.

New subject: 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.

Ivan Lazar Miljenovic

7:41 a.m.

On 28 August 2010 21:33, Johannes Waldmann 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.Miljenovic@gmail.com IvanMiljenovic.wordpress.com

Johannes Waldmann

7:52 a.m.

New subject: 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

Gábor Lehel

7:53 a.m.

On Sat, Aug 28, 2010 at 1:41 PM, Ivan Lazar Miljenovic wrote:

...

On 28 August 2010 21:33, Johannes Waldmann 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.Miljenovic@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.

Alexander McPhail

4 Sep 4 Sep

5:01 a.m.

Hi Is there a similar ticket for GHC to not export instances in the case that other instances are explicitly specified? module Foo ( Foo(Monad) ) instance Monad Foo where ... instance MonadState (Foo Bar) where ... i.e. the monad instance gets exported but the MonadState one does not? This helps in maintaining opacity with respect to the package user. I may not want the user to be able to call 'get' and 'put' when using my custom monad. Cheers, Vivian On 26 August 2010 02:20, David Waern wrote:

...

2010/8/25 Alexander McPhail :

...
Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter?

Yes, it should. BTW, we have a trac ticket for it:

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

You can add yourself to the CC list to show that you want this feature.

Currently we don't have many people working on these types of tickets in Haddock (I'm mostly fixing bugs, others are working on bigger improvements), so if more people would volunteer to help out, that'd be great. The mailing list haddock@projects.haskell.org can be used to ask for directions and help.

David

-- --- yolar et elver. --- DISCLAIMER This transmission contains information that may be confidential. It is intended for the named addressee only. Unless you are the named addressee you may not copy or use it or disclose it to anyone else.

Ivan Lazar Miljenovic

6:03 a.m.

On 4 September 2010 19:01, Alexander McPhail wrote:

...

Hi

Is there a similar ticket for GHC to not export instances in the case that other instances are explicitly specified?

module Foo ( Foo(Monad) )

instance Monad Foo where ... instance MonadState (Foo Bar) where ...

i.e. the monad instance gets exported but the MonadState one does not? This helps in maintaining opacity with respect to the package user. I may not want the user to be able to call 'get' and 'put' when using my custom monad.

No: instances are implicitly imported and exported (if the class and the type are visible, then so are any possible instances). -- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com IvanMiljenovic.wordpress.com

5373

Age (days ago)

5383

Last active (days ago)

List overview

Download

10 comments

5 participants

participants (5)

Alexander McPhail
David Waern
Gábor Lehel
Ivan Lazar Miljenovic
Johannes Waldmann