Re: Scwm docstrings change

["Greg J. Badros" <gjb at cs dot washington dot edu>]

mstachow@alum.mit.edu writes:

<snip>

> > 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.

Right, but those that do end up looking at the source aren't going to be 
confused by a macro used for function headers when done consistently and 
pervasively.

> > 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.

I don't see them as orthogonal in most cases.  I simply want to declare
a new primitive foo;  I'm not thinking about writing a C function foo
and exposing it to guile, I'm just interested in making the primitive
available.

I do like Michael's suggestion to provide both capabilities because it's 
clear that others (e.g., you! :-), but I'm sure there are more) do think 
of the two pieces separately.

> > 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.

But remember, I'm moving away from the static view of the whole program
and to a cpp-based doc-extraction system where we only will get the
stuff that's contained in the macro.  The checking of invariants will be 
done based on the whole source since it still makes sense for those
invariants to be maintained in code that's conditionally-compiled-out,
but it is confusing to have a primitive that was not compiled exist in
the documentation.

> 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.

I basically agree, but you're missing that the argument list would need
to be duplicated to provide reflection capabilities.

> 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.

From the trickle of much-appreciated opinions, people seem to fall on
the separate side, but I'm not sure that everyone understood the
argument list issue.

Here's the bottom line.  *Any* docstring extraction system provides a
tremendous benefit over the current state of affairs.  With Scwm I've
gained a lot of experience making the one I propose practically useful.
I will implement it for Guile as it is in Scwm, modified with the
capability to support separate hookups as Guile currently does, but will 
change the source to use the Scwm-style technique.

One of the problems Guile development has had is that we all have
opinions and we're all perfectionists.  In my opinion it's often better
to have a potentially imperfect evolvable solution that someone (here
me) is willing to implement rather than stagnating while discussing
incremental issues far overshadowed by the big picture. I'm willing to
go out on a limb a little bit by taking action;  worst case is we gain
some experience and have to back out a change or two.  That doesn't seem 
so bad to me.

Greg