On Sun, Jul 04, 2010 at 09:55:53PM +1000, Ivan Lazar Miljenovic wrote:

Andrew Coppin writes:

...

In summary, I think we need to devise a way of better-documenting class instances.

Haddock 2.7 supports documenting instance implementations; I don't know how this works, but according to the Changelog it's available.

Now we need to go round and document our instances. Hmm, it seems only partial: documentation attached to an instance is shown in the list of instances under a type, but not the list under a class.

On Sunday 04 July 2010 14:07:03, Ivan Lazar Miljenovic wrote:

Ross Paterson writes:

...

On Sun, Jul 04, 2010 at 09:55:53PM +1000, Ivan Lazar Miljenovic wrote:

...

Andrew Coppin writes:

...

In summary, I think we need to devise a way of better-documenting class instances.

Haddock 2.7 supports documenting instance implementations; I don't know how this works, but according to the Changelog it's available.

Now we need to go round and document our instances.

Hmm, it seems only partial: documentation attached to an instance is shown in the list of instances under a type, but not the list under a class.

I'm guessing that's to reduce noise...

I'm guessing it might have something to do with the fact that often the module containing the class definition isn't processed together with the module containing the instance declaration.

2010/7/4 David Waern :

2010/7/4 Daniel Fischer :

...

...

...

Hmm, it seems only partial: documentation attached to an instance is shown in the list of instances under a type, but not the list under a class.

I'm guessing that's to reduce noise...

I'm guessing it might have something to do with the fact that often the module containing the class definition isn't processed together with the module containing the instance declaration.

Actually Haddock attaches instance information to the modules in a separate step after having processed all of them. The fact that no documentation shows up for instances under the class documentation is a bug, embarrasingly enough, which I hadn't noticed. Looking at the code, it's not that I've forgotten to add code to the Html backend, it's something deeper that is wrong, so I will have to investigate.

I found the bug and fixed it, it's in the latest darcs version at http://code.haskell.org/haddock. David

On Sun, Jul 04, 2010 at 02:32:35PM +0200, Daniel Fischer wrote:

On Sunday 04 July 2010 14:07:03, Ivan Lazar Miljenovic wrote:

...

Ross Paterson writes:

...

Hmm, it seems only partial: documentation attached to an instance is shown in the list of instances under a type, but not the list under a class.

I'm guessing that's to reduce noise...

I'm guessing it might have something to do with the fact that often the module containing the class definition isn't processed together with the module containing the instance declaration.

It could be either way: sometimes you define a new class with instances for existing types, and with the current implementation that produces no documentation. (I tested with type, class and instance in the same package.)

On Sunday 04 July 2010 14:03:51, Ross Paterson wrote:

Now we need to go round and document our instances.

Hmm, it seems only partial: documentation attached to an instance is shown in the list of instances under a type, but not the list under a class.

Not much of a problem. Right-click on the type-link, open in new tab. Except for orphan instances, I presume.

David Waern writes:

2010/7/4 Ivan Lazar Miljenovic :

...

Andrew Coppin writes:

...

In summary, I think we need to devise a way of better-documenting class instances.

Haddock 2.7 supports documenting instance implementations; I don't know how this works, but according to the Changelog it's available.

It's simple:

...

-- | Documentation for the instance instance Monoid Foo

It's not for each method, just for the overall instance? I was kinda hoping to use it to be able to put runtime bounds on instances of some classes :( -- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com IvanMiljenovic.wordpress.com