Re: Standard Euphoria Library project
- Posted by Gordon Webster <gwalias-bb at yahoo.com> Jul 17, 2005
- 623 views
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 > - <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