OpenEuphoria

Re: Standard Euphoria Library project

• Posted by Derek Parnell <ddparnell at bigpond.com> Jul 18, 2005
• 578 views

cklester wrote:
> 
> Derek Parnell wrote:
> > cklester wrote:
> > > Gordon Webster wrote:
> > > > One question ... should we implement a really (really) simple
> > > > self-documenting
> > > > system?
> > > > 
> > > > -- Module: SimpleHashTables.e
> > > > -- Part of the Euphoria Standard Library
> > > > -- Contributed by Joe Coder, July 2005
> > > > --start-eudoc
> > > > -- SimpleHashTables.e
> > > > -- Hashtables of key/value pairs. Keys and values can be any Euphoria
> > > > Object
> > > > -- Duplicate keys and the removal of duplicates are now also supported.
> > > > --end-eudoc
> > > 
> > > Without enclosed comments (like /* comments [newline] more comments */,
> > > this
> > > kind of documenting would be horribly inefficient. Having to manually
> > > manage
> > > all the line breaks? Imagine inserting or deleting text.  We need
> > > multi-line
> > > commenting before this would be viable.
> > 
> > Hmmm... not so sure about that. I've been using this style of documention in
> > Win32lib
> > for years now and I've not had problems.
> 
> That's because you're weird!!! :D
> 
> I'm much more for this:
> 
> /-- new start of lines of comments marker
> Okay, now I can do whatever I want here... I don't have to worry about those
> stupid dashes at the beginning of each line. Later, if I need to make
> revisions,
> I don't have to worry about manual line breaks. This is only a concern because
> I've done it for in-house projects and I don't do it anymore. :/
> --/ -- new end-of-lines-of-comments marker, with current method on this line,
> too.
> 
> than this:
> 
> -- Okay, now I can do whatever I want here... I don't have to worry about
> those
> -- stupid dashes at the beginning of each line. Later, if I need to make
> revisions,
> -- I don't have to worry about manual line breaks. This is only a concern
> because
> -- I've done it for in-house projects and I don't do it anymore. :/
> 
> especially when it comes time to update the paragraph and insert a sentence
> or remove some words.
> 

I use a tool to format the text into presentable reading format, the source code
documentation is not meant to be the the finished product. I update paragraphs
and add/delete words all the time but the formatter makes it all pretty again for
me.


-- 
Derek Parnell
Melbourne, Australia
irc://irc.sorcery.net:9000/euphoria