Re: Standard Euphoria Library project
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.
>
> > > Please note my paragraph is perfectly justified. :D
> >
> > But is it justifiable? 
>
> Demonstrably.
>
> -=ck
> "Programming in a state of EUPHORIA."
> <a
> href="http://www.cklester.com/euphoria/">http://www.cklester.com/euphoria/</a>
>
Multi-line comments might be nice, but they're not valid Eu syntax
at the moment and therefore moot.
Anyway, I don't think that the dashed lines are so bad ...
they make it easy to see what's compiled and what's not and since
they are what we have to work with right now, I would propose that
we must stick with them.
... and please, please, please, nobody suggest code preprocessors!
The standard library modules must be VANILLA euphoria that compiles
right out of the box without dependencies on any other language
"bolt-ons" that will only add complexity.
It seems like many of us here love the almost zen-like brevity and
simplicity of Euphoria or we'd be using other, uglier languages. I
feel strongly that we should strive for this same brevity and
simplicity in the standard library. If this documentation idea is
going to detract from that, I would say let's scrap it - but if we do
decide to go with it, let's keep it really (really (really)) simple.
Best
Gordon
|
Not Categorized, Please Help
|
|
