Re: Documentation

[Michael Livshin]

Neil Jerram <address@hidden> writes:

> I mean that I don't immediately see how one can make the distinction
> between applying to a symbol and applying to a particular binding.
> With the current module system and with Scheme in general.  But I'm
> probably just missing something - am I?

well, it always may be me.  I thought you meant that sometimes it is
desirable to document a "name", so to speak.  so you say something
like "one of the exports of the module (foo) is bar.  it's supposed to
be bound to a list of widgets".  you, thus, document the exported
binding whose name is `bar' and which is exported by the module `foo'.
you don't document the symbol `bar' itself, which is just an object.

ouch, the more I try to explain things, the more confusing they
seem. ;(

>     Michael> one feature I like very much about the Lisp family of
>     Michael> languages[1] is the syntactic flexibility.  which means
>     Michael> that you can't really know a lot about code if you only
>     Michael> look at its printed representation (i.e. the source
>     Michael> file).
> 
> OK.
> 
>     Michael>         which means that specifying tools which are
>     Michael> external to the system proper whose purpose is to analyze
>     Michael> printed representation of Lisp/Scheme code is, at best,
>     Michael> kludgy.
> 
> Agreed.  (I'm not aware of having proposed anything like this - do you
> think that I have?

er, yes.  that said, I'm actually having some trouble, at this point,
with associating different proposals and major/minor points with
people who made them, so I just address the points themselves.  I can
see now it's not such a good strategy after all.  sorry about that.

> The only external tool that I have proposed is
> limited to looking at comments.  Er... OK, plus `(define ...)'
> expressions starting in column 0 - are you saying that even this very
> basic level of analysis would be too much, IYO?)

well, it's actually pretty conservative.  but I'd like to make it
unneeded.

> I'm sorry if I appear to have been jumping between proposals - an
> unfortunate consequence, perhaps, of trying to take everyone's
> comments seriously.

it's very much appreciated.  heck, I know someone whose snotty
comments all but beg "ignore me" at times.  *blush*

> In detail...  Everything in my Scheme docstring format proposal still
> stands.  Several people have expressed support for (i) the
> documentation in comments approach, for various more or less
> `cosmetic' reasons, (ii) the idea of only loading docstrings into the
> system when they are needed, to reduce Guile's memory footprint.

all good things, and I want them too.

> On the other hand, other people have expressed support for the
> documentation in code approach, noted that docstrings should be
> associated with values rather than names, etc. as summarized in my
> last but one email.

there's no contradiction.

> I think we can support both approaches, and don't see the need to
> decide between them.  The way to do this - as per my second proposal -
> is to say that the "documentation in code" approach is primary, and
> that snarfing tools are free to generate any code or data that can be
> used in some way by the documentation code.

this is where you lose me.  hmmm.  ah, I think I see.  you think that
points (i) and (ii) are only addressable through snarfing, right?

> But what about the people who specifically _want_ documentation
> information to be lost when code is loaded?

would "sit in the database and don't fill up the memory until I ask
for you" be an adequate substitute for "get lost"?  then I have this
concern in mind.

> Or those who find editing multiline Scheme strings significantly
> more awkward than comments?

this is addressable too, I believe.

I propose we introduce a new reader syntax for embedded documentation.
let's say #{...}#. (it's probably taken, but as I'm still in
handwaving mode...)

upon encountering this syntax, the reader will:

* store the text in the online database (dbm would do nicely).
* yield, as the read value, some lightweight ID which uniquely
  identifies the stored string (a running counter would do nicely as
  the key, I think).  this ID is what the 'documentation object
  property actually stores.

note that Martin already posted a dbm binding to guile-sources, so he
must be thinking along the same lines. ;)

the above takes care of the first problem.  the second problem is
addressable by teaching Emacs to treat the #{...}# syntax like
comments, which shouldn't be very hard.  the important point is that
it's not confused with the regular string syntax.

> I'm particularly keen to understand your point here, because the idea
> of `just using the module system' has occurred to me too, although
> probably in quite a different context.  My idea is that we could use
> the module system to automatically track whether docstrings have
> already been loaded or not, and that the mechanism that we use to
> cause a module to be reloaded could be the same mechanism that we use
> to cause docstrings to be reloaded.
> 
> So, for module (blah groop), the corresponding docstrings could be defined
> in module (blah groop documentation) as a sequence of document!
> expressions:
> 
>   (define-module (blah groop documentation)
>     :use-module (blah groop))
> 
>   (document! blah-file "...")
>   (document! blah-file-list "...")
>   (document! blah-port "...")
> 
> (Note that this file could be generated automatically as the result of
> snarfing docstring comments from the Scheme file for (blah groop).)
> 
> This would be loaded by `(use-modules (blah groop documentation))',
> which automatically takes care of only loading the file once.

this looks like a very elegant solution to a problem that I'm trying
to avoid entirely. ;)

> What was your idea about using the module system?

well, as it organizes all the modules and bindings and objects in a
neat hierarchy, it seemed a good idea to use this hierarchy to
generate external documentation.  like the reference manual. ;)

this does mean that in order to generate the chapter about, say,
regexps, you'll have to actually load the regexp module into Guile.
which may be a problem...

incoherently yours,
--mike

-- 
Make sure your code does nothing gracefully.