OpenEuphoria

Re: Standard Euphoria Library project

• Posted by "Juergen Luethje" <j.lue at gmx.de> Jul 25, 2005
• 625 views

I'm very sorry for the late reply.

Gordon Webster wrote:

> 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?

I like it, and there seems to be agreement here, right?
I've added a corresponding note to
<http://home.arcor.de/luethje/esl/road_map.htm#doc>.
Maybe that note should be more detailed?

Regards,
   Juergen