Re: [Chicken-users] docstrings

[tonyg]

> In an interactive programming environment of the smalltalk or lisp
> machine variety, they sort of made sense at one time, but a lot of
> what they do now could probably be done just as well with emacs and
> tags, couldn't it? Is it really useful to add that storage to compiled
> code when we mostly aren't doing interactive stuff anyway?

Well, I see interactive experimentation and exploration as a huge win,
and part of what makes Scheme and Python attractive to me. Just that I
can try out little ideas to remind myself of argument ordering, say,
or define little tests to see how a feature works or a routine returns
failure. (I really enjoy Squeak Smalltalk's Browser, too...)

Whenever I've had a break from scheme for a while I always find myself
doing things like

        >>> (assq 'a '((a 1)))

to remind myself of how assq works :-)

Also, these docstrings aren't *just* for interactive use: in fact, the
main reason I'm interested in them is for user-guide autogeneration,
like Javadoc or Doxygen. The old WEB-style idea of keeping the code
and the docs together...

I imagine there'd be a compiler switch or a (declare) to turn off
docstring retention in compiled code, too. For production code you
don't want to be shipping a mass of internal documentation... but
during development I think it helps me to work more quickly when I
have documentation trivially accessible.

        >>> (require 'oracle)
        >>> (documentation db:oracle-connect)
        ((db:oracle-connect username/password)
         "Connects to Oracle with the given username and password string,
        returning a database connection object suitable for use with
        DB:for-each et al.")

Tony
-- 
Monkeys high on math -- some of the best comedy on earth
        - Tom Lord, regarding comp.lang.scheme