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