[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Documentation

From: Neil Jerram
Subject: Re: Documentation
Date: 27 Feb 2001 19:31:28 +0000
User-agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.5

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

    Michael> Neil Jerram <address@hidden> writes:
    moi> the intention is to document a binding, right?  so the above
    moi> will document the binding in the current module named by
    moi> 'case-fold-search, and not the symbol 'case-fold-search?
    >>  Good point - I have no idea whether/how this would work.

    Michael> do you mean how this would work with the current module
    Michael> system or how this would work in general?  because in
    Michael> general (i.e. theoretically), I don't see any problem.

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?

    >>  This is the main thing that I don't get.  Could you explain a
    >> little more?  Who and when would call `snarf-docs',

    Michael> I think it would be prudent to explain my motivation at
    Michael> this point.

    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).


    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?  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?)

    Michael>          it would only work through convention.  having
    Michael> tools that work only through convention is probably
    Michael> acceptable in practice, but I'd rather avoid that if it's
    Michael> possible.  and I happen to think it _is_ possible.

    Michael> problem is, I don't really know any more whether you
    Michael> agree with this or not.

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

Overall...  My only agenda is to try to encourage more and better
documentation, in whatever format, since
- I believe it enhances the Guile development environment
- it provides more raw material for the reference manual.

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.

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.

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.

    Michael>                          I _assumed_ you don't agree,
    Michael> thus I wrote up the above sloppy mini-proposal, so that
    Michael> you would see that if documentation information isn't
    Michael> lost when code is loaded, then there's no need at all to
    Michael> _guess_ things about printed representation of said code
    Michael> -- we could just interrogate the module system and find
    Michael> things out for sure.

But what about the people who specifically _want_ documentation
information to be lost when code is loaded?  Or those who find editing
multiline Scheme strings significantly more awkward than comments?

    Michael> so perhaps the mini-proposal might have not been called
    Michael> for.  in that case, sorry.  I hope that's clearer now.

Perhaps, but I still have the feeling that I have not understood what
you mean when you talk about the module system (e.g. `just interrogate
the module system').

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!

  (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.

What was your idea about using the module system?

Best regards,


reply via email to

[Prev in Thread] Current Thread [Next in Thread]