[Top][All Lists]
[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