Re: Scheme documentation question

[Russ McManus <russell.mcmanus@gs.com>]

Tel <telford@eng.uts.edu.au> writes:

> > > Summarized: this way, documentation is easily and flexibly generated by
> > > developers, extracted by parsers and customized by guile users.
> > 
> > Actually, having the doc strings right inside of Lisp forms at defined
> > locations is also quite easy to parse.
> 
> Until later on you decide to extend the system even further and support
> international documentation which uses a single token in the place
> of each docstring but then realise that there are already legitimate
> cases where a similar token might be used in a function definition.

Excellent point.  But why couldn't you have a convention about what
these tokens look like?  In Emacs, they have implemented a notation
for specifying calling conventions that uses a form called
'interactive'.  In runnable code, 'interactive' is a function that
does nothing.  You could have a form called 'docstring' that worked
similarly in guile, that supported internationalization, and that had
the documentation inside of defining forms.

> You might decide to have a function that returns docstrings but your
> parser is set to look for strings and doesn't know whether this
> function is designed to return a string or whether there is no
> documentation and this function is part of the real definition.

Does my proposal addresses this valid point?  I think docstrings
should be right in the source, and that with some creativity, no
generality will be lost.

-russ

--

We're too busy mopping the floor to turn off the faucet.