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