Re: Scwm docstrings change

[mstachow at alum dot mit dot edu]

"Greg J. Badros" wrote:
> 
> 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.

Fine, let's call the issue one of esthtics rather than clarity. I think
the Guile-style separate

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

I agree with the suggestion of providing both versions as well. I think
`SCM_HOOKUP' is not a very good name however. I think `SCM_PROC' for
the current separate version and `SCM_DEFINE' for the integrated version
(on analogy with emacs's `DEFUN' macro) would be reasonably good names.

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

So are you saying you will just run the program through CPP and out pops
the ready to use result, or that you will run it through cpp and then
postprocess the results in some way? If the latter, I don't see how having
to find function definitions is such a big deal.

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

I think I stated in the earlier message why I don't think that is the case.
(In brief: reflection information can be stored in the same external location
as docstrings and similarly demand-loaded). If it really would be highly
impractical to do reflection of this kind without having the argument
list in the macro, then I will change my stance since duplicating the
C argument list is clearly bogus. 

However, (warning, quarter-baked thought approaching) perhaps it would
be better to make the macro include a scheme-style argument list, since
this would allower better control of how the formal parameter names will
look to the user. The function name is already written once in Scheme style
and once in C style. Indeed there are already cases in the Guile sources
where the Scheme and C names for functions or syntax do correspond in
the canonical way (`atapply' would normally become the Scheme `atapply'
rather than `@apply' for instance), and it may be the same thing might
be useful for formal parameters in some cases.

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

I agree that anything is better than what we have now (i.e. nothing) and
that both variants should be provided, since there's at least one advocate
for each so presumably people may wish to do their applications in one
style or the other. But I think the Guile sources should be left in the
separate style. If both variants are to be supported then which one the
Guile sources use is really just a matter of taste, and my taste at least
prefers having the function header separate.

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

I'll agree in general that there has perhaps been a bit too much
perfectionism. But perfectionism does have its advantages as well,
especially in the case of widely used libraries - doing something
one way and then releasing it makes it very difficult to move
elsewhere in the design space because the need for backwards
compatibility and the

I don't think anyone has any objection to the docstring system other
than mine about the syntax, and I think we are pretty close to
agreement on that anyway. The only reason I bring it up now is
because I know that changing the SCM_PROC macro either way will require
a large pervasive change to the Guile sources, and if we change our
minds about how to do it, that change will have to happen again.

I think it's really great that you are doing this, and I want to
make sure it gets done in a way everyone can like as quickly as
possible so that a release of Guile with complete reference
documentation can be made as soon as possible. My quibbling over
this one fairly small point should not be construed as anything
other than a way to minimize the time to a releasable version
with full reference docs.

 - Maciej