A Haskell Documentation Standard

[Simon Marlow]

> That means that classes and instances (and their functions) have to be
> distinguished by giving the complete type of the class / instance
> declaration, right?
> 
> E.g.
> 
>   class X a b where
>      f :: a -> b
> 
>   instance X Person Frog where
>      f x = ...
> 
> How do we avoid that the tool confuses the two version of "f" ?
> An obvious way would be
> 
>      {-# DOC f INSTANCE X Person Frog ... #-}
> 
>      {-# DOC f CLASS    X             ... #-}

For classes, the 'class' keyword isn't required: classes and type
constructor share the same namespace, so an identifier beginning with an
upper case letter is unambiguous.

I hadn't considered the documentation of individual instances, but
perhaps you need that for internal documentation (most of the time, the
only documentation you need for an instance is that it exists).  If
documentation for instances is required, then yes, you have to give the
full instance header in order to identify the exact instance.

> (HDoc required similar "help" in early versions, but I changed that in
>  favour of considering positional information to reduce the redundancy
>  required in the annotations.)
> 
> 
> I guess additional annotations are an unavoidable drawback when not
> relying on positional information. On the other hand, being 
> able to put
> the documentation in different files may be a big advantage.
> 
> So, should we allow both variants? I.e. use positional 
> information when
> the pragma happens to be next to a class/instance declaration (or a
> function therein) and rely on extra information (like "CLASS 
> X") in the
> other case?

I wouldn't object to allowing both variants - perhaps the convention
could be that if the identifer is missing, then it applies to the
following declaration.

PS. Henrik - before this discussion gets too detailed, do you want to
announce the existence of the mailing list on haskell@haskell.org?

Cheers,
	Simon