This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Re: Scwm docstrings change
mstachow@alum.mit.edu wrote:
>
> "Greg J. Badros" wrote:
> >
>
> > I am unconvinced. The average C programmer shouldn't be reading the
> > Guile source anyway. It's far more important that the invariants
> > between the two parts be clearly intimately tied (and statically
> > checked, though separating them would only complicate, not eliminate,
> > the static checking that scwmdoc does).
>
> I don't think the checks are bad (as I said below). However, I don't
> think making the checking slightly more difficult is a higher cost
> than making the code even a bit less clear.
>
> > Sorry, but I have to disagree here, too. Guile should be able to be
> > viewed as a black box to application developers. Those that do have to
> > go poking into Guile should be even *more* sophisticated than those
> > reading just an *application* that happens to use the interpreter.
>
> I disagree. While every library should have sufficient documentation
> that reading the source code is never _necessary_, it is often useful,
> and in a free software project it is essential that it be possible and
> easy. Many times I've found myself looking at the source for even
> well-documented libraries like GNU libc or Tcl for various reasons.
>
> > Yes, it's possible. But it's worse: the name foo_proc is duplicated
> > creating yet another point of mismatch that the C language (via cpp)
> > *can* avoid.
>
> I don't think typing the name of the function twice is bad, especially
> since it is being used in two orthogonal capacities - once to declare
> the function, and once to register it as a Scheme procedure. I also
> do not think there will be a lot of errors resulting from this
> duplication.
>
> > Also, SCWM_PROC exposes the argument list to scwm_make_gsubr. This
> > permits better reflection capabilities for the primitives so that they
> > can support, e.g., `procedure-formals' and `procedure-required-formals'
> > (see Scwm's reflection.scm). Duplicating the argument list is out of
> > the question, and getting this feature w/o exposing the argument list is
> > hard.
>
> I'm not sure if revealing the names of the formals that way is essential.
> They are already included in the doc string generated by the extractor,
> and I can't think of a lot of ways that the identifiers used for the formals
> would be useful programmatically. And further, if the reflection information
> were to be stored externally and generated by the doc extractor (IMO a
> reasonable strategy in any case), then not having the formals in the
> SCM_PROC call presents no additional challenge.
>
> I think we are on the same page with regards to what functionality we
> want provided. I think the differences between the two approaches boil
> down to this:
>
> SCM_PROC expands to function header | function must be declared separately
> ----------------------------------------|----------------------------------------
> Doc extractor is somewhat simpler | Doc extractor somewhat more complex
> |
> Function name stated only once | Function name stated twice
> |
> Somewhat less immediately | More immediately comprehensible
> comprehensible |
>
> I think it's a worthwhile tradeoff to do a bit more work in the extractor to
> make the code a bit more readable.
>
> But I would like to hear other people's opinions on this - surely people
> other than Greg and me must have a preference one way or the other.
>
> - Maciej
I agree with Maciej. I think for a C-prgrammer occasionally writing a
guile extension it is more convenient to define functions the usual C
way and bind them separetely. I recollect that when I looked at the
emacs sources (it was version 18 something) I was surprised with the way
it defines primitive elisp functions (which was somewhat similar to
Greg's suggestion). It was not that it's hard to comprehend. I just feel
that it's a bit unnatural. I was glad to see how guile does it.
Regards,
Aleksey