Re: Scheme documentation question.

[Greg Badros <gjb@cs.washington.edu>]

"Harvey J. Stein" <hjstein@bfr.co.il> writes:

> Can anyone explain to me why define-public for functions looks like:
> 
>    (define-public (fname arg1 arg2 ...)
>       "quoted string containing documentation..."
>       body)
> 
> whereas define-public for variables looks like:
> 
>    (define-public variable value)
>    ;;;**VAR
>    ;;; Scheme comment containing documentation...
> 
> I realize that doing:
> 
>    (define-public variable doc-string value)
> 
> would break lots of code, but how about:
> 
>    (define-public variable value optional-doc-string)
> 
> Can't this be made to work?

This is a question more for the guile folks I think.  Variables don't
have doc strings attached.  We could add a syntax:

(define-documented-variable VAR DOC-STRING VALUE)

I suppose, but I'd rather have something that's guile-supported.  (I'd
prefer that the order stay the same as for procedures).

> Why am I so concerned?  Because scwmdoc.scm can trivially snarf up the
> documentation for the fcns by just doing (read), but can't get the
> documentation for the variables this way.  It'll have to do all sorts
> of ugly hacks such as snarfing up the form, then if it's a variable,
> doing readline for the docs, & if it doesn't start with ;;;**VAR, then
> do all sorts of messed up stuff to read it as the beginning of a form
> because one might run into:
> 
>    (define-public variable1 value1)
>    (define-public variable2 value2)
> 
> Also, an efficiency question.  In guile, strings eval to themselves.
> In the define-public defuns, do the strings become part of the body of
> the functions & get evaled each time the fcn is executed?

(just left this stuff in for guile folks to respond to if they so choose).

Greg