guile-devel
[Top][All Lists]
Advanced

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

Re: Questions about docstrings


From: Neil Jerram
Subject: Re: Questions about docstrings
Date: 27 Mar 2001 19:23:52 +0100
User-agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.5

>>>>> "Martin" == Martin Grabmueller <address@hidden> writes:

    Martin> 1. Some docstrings contain a `(r5rs)' at the end, which is
    Martin> obviously meant to show to which standard the procedure is
    Martin> conformant.  I think this should be removed, because R5RS
    Martin> procedures can be looked up in the R5RS-index in the
    Martin> reference manual.

I agree.  More generally, r5rs-compliance is an easily-reproducible
property, if, say, we wanted to implement some kind of
`relevant-standard' property in the future.

    Martin> 2. Some docstrings contain two pieces of documentation,
    Martin> where the second is prefixed with `(qdocs:)'. What does
    Martin> that mean?  If it is just bitrot, I'll remove it and make
    Martin> the whole docstrings more consistent.

Some time ago, when documentation was a rarer commodity than it is
now, Greg Harvey (working on the GC at the time) wrote the "qdocs" as
a guide for himself and others on Guile internals.  When Greg Badros
did the initial docstring work, some of these qdocs were used for
docstring text in addition to other sources such as rnrs, and no one
quite got around to unifying the docstring as a whole.

In other words, yes, it's sort of bitrot, and it would be excellent
to make the whole docstring consistent.

Regards,
        Neil



reply via email to

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