OpenEuphoria

Re: Standard Euphoria Library project

• Posted by D. Newhall <derek_newhall at yahoo.com> Jul 18, 2005
• 601 views

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.
>
snip 
>
> This way, all the procedure signatures could be parsed out with their
> documentation and turned into text or html.
> 
snip
> 
> What do you think?

I had the same idea a while ago so I started a program to do that. Oddly enough
I just started working on it again and it should be availabel soon. It produces
html files that look like the official Euphoria library routine documentation.

Here's how it works (taken from the opening comments to the program (named
eudoc.ex)):

-- Name:         EuDoc - Euphoria documentation program
-- Author:       D. Newhall
-- License:      Mozilla
-- Date:         Feb-7-2005
-- Updated:      Feb-14-2005
-- Updated:      Jul-13-2005
-- Intro:
--  EuDoc is a program for automatically creating documentation
--  for Euphoria libraries. The file created has the same visual
--  appearance as the library routines list in the official Euphoria
--  documentation. It can also be used to document programs but in a 
--  more limited scope.
--
--  For EuDoc to work you first need to document your program using these tags.
--  The tags are case insensitive and need not be in any order but it's highly
--  recommended that you use the capitalization scheme and order shown for
--  better clarity.
--
--  File secriptor tags:
--
--    Name:            Name of library/program. Required
--    Author:          Author's name
--    Date:            Date file was created
--    Updated:         Date file was updated
--    License:         License library's source code is released under
--    Requires:        Other files the library requires
--    Intro:           Introduction comments about the library
--
--  Routine descriptor tags:
--
--    Routine:         Name of the routine. Required
--    Author:          Aurthor of the routine
--    Date:            Date routine was created
--    Updated:         Date routine was updated
--    Platform:        Platform the routine runs on
--                     (General, WIN32, DOS32, Linux, FreeBSD)
--    Syntax:          An illustration of the usage syntax
--    Description:     A description of what the routine does
--    Comments:        Extra comments about the routine
--    Example:         A more example to illustrate usage
--    Example Program: The name/location of an example program if such 
--                     a program exists
--    See Also:        Lists other related routines in the library


So for the upper() funtion in wildcard.e you'd type:

--------------------------------------------------------------
-- Routine:  upper
--
-- Description: 
--   Convert an atom or sequence to upper case. 
--
-- Example:  
--
--   s = upper("Euphoria")
--   -- s is "EUPHORIA"
--
--   a = upper('g')
--   -- a is 'G'
--
--   s = upper({"Euphoria", "Programming"})
--   -- s is {"EUPHORIA", "PROGRAMMING"}
--
-- See Also:  lower  
--------------------------------------------------------------
global function upper(object x)
    return x - (x >= 'a' and x <= 'z') * TO_LOWER
end function

and from this you'd get documentation that looks exactly like the official
library documentation (in theory). Whitespace/formatting is ignored where
unimportant.