guile-devel
[Top][All Lists]
Advanced

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

Re: Documentation


From: Rob Browning
Subject: Re: Documentation
Date: 12 May 2001 14:50:12 -0500
User-agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7

(Sorry for the late reply.  I'm catching up on the last bits today
 from when I (re)joined a while back.  Also, if this has been fully
 resolved since, just take my comments as commentary :>)

Neil Jerram <address@hidden> writes:

> Agreed.  In fact, I did a little more experimentation, and found that
> Emacs fills multiline strings in Scheme mode quite nicely.  The only
> slight annoyance is the indentation and quotation mark at the
> beginning, which tend to make the first line of the documentation too
> short.  But this annoyance could be overcome by writing docstrings
> like this:
> 
> (define/documented (make-foo bar)
>   "\
> Make and return a new foo using the template @var{bar}."
>   ...)
> 
> We just need to persuade Emacs not to fill back onto the `"\' line.
> So perhaps we don't even need a new string syntax.

And this has the distinct added advantage of not making the function
definitions *much* harder to parse by a non-Guile Scheme.

With #{}# any other reader would just choke on the definition, and it
would be difficult to fix (aside from just deleting the docs.  With
either a string, or the stuff I think Marius had mentioned (i.e. a
special form:

  (define (foo bar)
    (doc :some-info ...
         :some-more-info ...
         :body "\
     ...)

I believe it should be possible to just write a standard R5RS macro to
drop (or rewrite) all the docs.

>     Michael>   1) docstrings take up memory.
> 
>     Michael>   I don't believe this to be a serious problem, actually.
> 
> No, but others may do, and I think we should take their opinion into
> consideration.

And I think it's probably a solvable problem, at least on systems
where we have demand paging, or can manage to put the documentation in
optionally loadable sub-files.

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



reply via email to

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