This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Scwm docstrings change


"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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]