Re: Standard Euphoria Library project

new topic     » goto parent     » topic index » view thread      » older message » newer message

Juergen Luethje wrote:
> 
> Jason Gade wrote:
> 
> > D. Newhall wrote:
> >> 
> >> Juergen Luethje wrote:
> 
> <big snip>
> 
> > One place to look before writing a bunch of new code is Derek Parnell's
> > tk routines <a
> > href="http://www.rapideuphoria.com/toolkits.zip">http://www.rapideuphoria.com/toolkits.zip</a>
> > and other
> > submissions to the archive
> > <a
> > href="http://www.rapideuphoria.com/cgi-bin/asearch.exu?gen=on&keywords=Parnell">http://www.rapideuphoria.com/cgi-bin/asearch.exu?gen=on&keywords=Parnell</a>
> > for some very good ideas.
> > 
> > Also Bernie Ryan's Utility Library <a
> > href="http://www.rapideuphoria.com/mixedlib.zip">http://www.rapideuphoria.com/mixedlib.zip</a>
> > 
> > Much of the C standard library can be found, especially in Derek's toolkit
> > routines.
> 
> Also let's not forget Ricardo Forno's General Functions library, and
> more ...  No doubt that there are many "diamonds" among more than 1400
> contributions.
> 
> However I think we should not look at all those valuable contributions,
> and then consider what will be the best way to put them all together.
> IMHO we should go the different way: Let's build a solid framework first,
> and then fill that framework with contents.
> 
> Furthermore, please see smile
> - <a
> href="http://home.arcor.de/luethje/esl/index.htm">http://home.arcor.de/luethje/esl/index.htm</a>
> - <a
> href="http://home.arcor.de/luethje/esl/esl_paper01.htm">http://home.arcor.de/luethje/esl/esl_paper01.htm</a>
> 
> Regards,
>    Juergen
> 

Wow Juergen, I checked out the links to your website. What a great start!!

I think your draft description of the library really encapsulates pretty much
everything we need to be thinking about and you've indicated where we might
want to fill in some of the finer details.

One question ... should we implement a really (really) simple self-documenting
system? I'm thinking of Python's system where the first block of comments
after the start of a module or procedure are treated as documentation for the
module or procedure itself and can be parsed out for documentation purposes. 
We might even have a little tag for the lines that should be parsed so that
authors could have some control to distinguish "doc" lines and other comments.

Here's an example of how it might look ...

-- 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
 
 <some declarations and other code here>

function hashTableGet(integer hashtable, object key)
-- 21st July 2005, Joe Coder's fixed the bug that arose with duplicate keys
--start-eudoc
-- Function hashTableGet
-- Returns the object that is the 'value' in the key/value pair specified
-- by the supplied key. The constant HASHTABLENULL is returned in the event
-- that the specified key does not exist in the current table
--end-eudoc
    <some function code here>
end function

This way, all the procedure signatures could be parsed out with their
documentation and turned into text or html.

If you wanted more detail, this model could easily be extended to be more
like 'javadoc' where authors and version dates etc. can also be specified. 
I personally think this is overkill. When I'm looking for a description of
how to use a Java hash table, I don't normally care who wrote it or what
version number we're at as long as it's the current official release. Most
times I just want to know how to use that library's functionality in my
code. That more detailed stuff can (and should) be included in normal
comments for those who need it but kept out of the 'eudoc' blocks to make
the documentation more concise and readable.

What do you think?

Best

Gordon

new topic     » goto parent     » topic index » view thread      » older message » newer message

Search



Quick Links

User menu

Not signed in.

Misc Menu