Re: Documentation

[Rob Browning]

thi <address@hidden> writes:

> well, i hereby exercise my right to foolishly backpeddle from my
> previous consensus-oriented stated opinion...  i now think docstrings
> being part of the lambda is not a good idea after all -- not actually
> standardized, somewhat ambiguous, not amenable to localization (gettext,
> AFAICT), as well as being gratuitously memory consumptive.

I'm not sure I understand.  The localization doesn't seem any harder
whether we put the docs into a comment or the body, and I still think
that with a little bit of cleverness we can arrange for the strings to
require as little memory consumption as desired, including 0.

As I believe people have mentioned, in cases where memory space is
critical, and there are no clever tricks we can play with demand
paging, a DB, or whatever, we just allow a switch that will cause
guile to discard the docstrings altogether while loading -- a simple
redefinition of lambda as a slightly different macro should handle
this.

In other cases, it seems like we can play all kinds of tricks to make
it possible to easily collect all the data, and do whatever we want
with it.  If we need to build one file (or DB) with all the
documentation, that should be possible in one pass over the code using
a slightly different definition of lambda, etc.

If we want the docs to be available at runtime but we don't want to
have it all in RAM all the time, we could do all kinds of things --
one option would be to just place all the docs in a DB and place
lookup keys in RAM.  We could even store the docs in compressed format
in RAM or in the DB if we really wanted to.

Also, if I misinterpreted you, and if your major concern is just over
having

  (define (x) docs ...)

vs

  (define (x) ...)
  (set-documentation! x docs)

It seems easy to write the latter as a macroexpansion of the former...

> i hope this waffling indicates that i'm not qualified for docstring
> processing (he says, hoping to shirk guile maintenance for a while
> and get back to Other Stuff ;-)...

:>

> btw, `use-modules' update and documentation is in.  feedback requested!

Great.

-- 
Rob Browning <address@hidden> PGP=E80E0D04F521A094 532B97F5D64E3930