Re: Documentation

[Neil Jerram]

>>>>> "Michael" == Michael Livshin <address@hidden> writes:

    Michael> Neil Jerram <address@hidden> writes:
    >> I can see the need for documenting a particular binding rather
    >> than a symbol, I'm just not sure how one can implement this.

    Michael> (with-waving-hands  [...]

OK, thanks, I see now how it can be done.

    >> Can you make the idea a little more concrete, though, by giving
    >> an example of the use of #{...}# and indicating what this read
    >> syntax would expand to?

    Michael> something like this:

    Michael> (define (foo ...)  #{ foo: do stuff }# ...)

    Michael> upon seeng the #{ prefix, the reader gets all excited,
    Michael> reads the text up to }# and does this:

    Michael> (%store-string " foo: do stuff ")

    Michael> this has the effect of storing the doc text in the
    Michael> database and returns a little smob that identifies this
    Michael> text.  [...]

This looks very nice!  I see now how we could read docstrings without
continuously increasing Guile's memory usage.  But I have two
concerns.

1. How much would the reading of #{ ... }# forms and the %store-string
   operation affect the time taken to load a module?  Is this time
   significant in comparison with reading in the code?  (Perhaps not,
   if most of the current read time is attributable to slow module
   lookup closures for variable references.)

   (Note that the %store-string operations could be done
   asynchronously w.r.t. the module loading, as long as they completed
   quickly enough to avoid the possibility of a backlog building up
   and so doing all the allocation that we're trying to avoid.)

2. Shouldn't we generalize this to cover storage of any arbitrary
   object in a database, using Keisuke's binary read/write to marshal
   objects into a flat format?

Best regards,

        Neil