On Tue, 14 Mar 2000, George Russell wrote:
> "D. Tweed" wrote:
> > Documentation is a vague term: certainly it'd be undesirable for a
> > specification to the libraries to just a literate copy of the code
> > itself. But if you're thinking in terms of an open source project where
> > people fix bugs in the libraries then libraries that contain some
> > explanation would be useful (as an additional item to the library spec).
> Couldn't agree more. Every module should be commented, and every exported
> symbol (and lots of the internal ones) should also be commented. But I don't
> think you need anything more than comment characters for this.
Well I think of, for example, Bird-tracks as an weird comment notation
where you mark the bits that aren't comments. The point is that there are
various uses for comments in code which it's helpful to be able to
distinguish by machine analysis:
* Long expository comments that can be displayed as paragraphs of natural
language
* Inline comments that should be displayed as small snippets within the
code
* Comments that actually contain meta-program information, eg pragmas
* Comments that have been used to remove sections of code temporarily
I think that things like JavaDoc, POD and python doc-strings can be viewed
as simple literate programming techniques or as comment conventions that
are machine analysable depending on your preference. Certainly I wouldn't
want to use {- -} braces for literate (ie long) comments without some
convention for auto-distinguishing them from other uses of {- -}.
___cheers,_dave________________________________________________________
www.cs.bris.ac.uk/~tweed/pi.htm|ALERT: you are communicating with an
email: [EMAIL PROTECTED] |unsavoury individual with a copy of gdb
work tel: (0117) 954-5253 |who reverse-engineered a file format.
