Positional cues or not

[Armin Groesslinger]

On Tue, 13 Feb 2001 malcolm-hs@cs.york.ac.uk wrote:

> > One problem with documentation comments: sometimes they are before the
> > definition of the commented thing, but sometimes after. They are before
> > functions (which are long) but might come aftre type definitions (which
> > are short). We should probably require them to come before.
>
> I don't see much difficulty in allowing both before and after positions,
> leaving it to the tools to re-format appropriately.  Why introduce a
> restriction?
>

I guess tools will get confused by


data A = A Int

---
-- bla
--

type B = String

---
-- blub

newtype C = C Bool


Is "bla" and "blub" in 'before' or 'after' position?
I don't like restrictions like disallowing empty lines before/after
the comments to help the tool find the right comments.

I'd prefer a convention I've suggested before: Association of comments and
source is done by either placing the comment before (or somewhere at
the beginning of) the thing to be documented, or - alternatively - by
explicitily mentioning the thing to document in the comment
(like "@DOC A" or somehting similar). This combination allows
  - comments next to the source
  - separate documentation in different files
Putting comments _after_ the definition is then - of course - possible by
giving a "@DOC".

Maybe I'm missing something here. So, what documentation scenarios are
not at all/not appropriately met by this dual approch?


Here's an example for my suggestion:

---
-- documentation with end-of-line comments

type B = ...


{---
  For those who like the other style.
-}
newtype C = ...


f :: Int -> Bool -> String
f ... = ...
        ...


g :: A -> B -> C
g a b
  ---
  --  documentation in Jan's style
  = ....

-----------


--- @DOC f
--  Here's the very long documentation for @f@ which I didn't
--  want to put into the source file....



Regards,

Armin