> Karlsson Kent - keka wrote:
>
> Well, that doesn't even look much like XML: it's not well-formed XML.
Personally I'd rather people spent time trying to make their comments clear,
rather than worrying about correctness of XML tags . . .
In any case, in the original example
<haskell:module>
<Name>Html</>
<Version>0.1</>
<Description>
Main import module for the Html combinators</>
<License>
The Haskell Html Library is Copyright ©
Andy Gill, and the Oregon Graduate Institute of Science and
Technology, 1999, All rights reserved, and is distributed as
free software under the license in the file "License", which
is included in the distribution.</>
<Author>
<A HREF="http://www.cse.ogi.edu/~andy">Andy Gill</a></>
<Restrictions>
This works with all Haskell 98 compilers.
</Restrictions>
<Tested>Hugs98, GHC 4.03</>
</haskell:module>
my main problem is that the useful content is almost null. Suppose I
am a maintainer of a complex program including this module. The only line
that will interest me is
"Main import module for the Html combinators".
(This is rather sparse. If this is a self-standing library, where is
the main user documentation? If it's written as part of a bigger program,
what part of the program is likely to use it and why?)
Who the author is, and what the version is, would be better handled by
CVS or some similar system. The "<Name>" is redundant; if it doesn't match
the filename, we have total chaos anyway. The <License> is a drag; I suspect
it could in fact be dispensed with in most though sadly not all of the civilised
world, where the presence of a "LICENSE" file in all distributions, or indeed
nothing at all, will secure automatic legal copyright protection. Of course
if your lawyers insist I suppose it has to be there . . . <Tested> and
<Restrictions> would be better handled by referring to a test case file
somewhere (with the output it's supposed to produce!), then I can see exactly
(A) what is being tested; (B) whether my new whizz-bang Microsoft Visual
Haskell compiler can pass these tests.
So my reformed comment would be
{- Top-level module for HTML combinator library.
See also test cases in tests/HTML.* and user-level documentation in
docs/html/HTML.html
<Other guff, EG places where the code could be speeded up or improved>
<License, if the lawyers say we've absolutely got to have it here>
-}
Of course the user-level documentation does not let the author out of putting
decent comments in the code as well.
Perhaps my main worry is that companies will think they are achieving something
if they force their developers to put XML compliant guff at the top of the
file, rather than taking the time to make their code intelligible to a human
reader in a hurry . . .
