Re: Scwm docstrings change

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

mstachow@alum.mit.edu writes:

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

You really need to figure out what's wrong with your mail-authoring
software.

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

Agreed.

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

Except that I'd like the post-processor to only have to deal with lines
that start with, say, %%%% as guile-snarf and scwm-snarf now do.  I can
actually get pretty darn close to the raw docstring output as it is w/o
any substantial postprocessing, but my goal is to just make the
postprocessing simple as it is fairly loosely coupled.

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

It's a solved problem one way, it's not solved the other way, and we
agree it's largely a matter of aesthetics;  I'm planning on moving
forward with the macro that keeps the coupling tighter and is more
concise.

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

We already do this in scwmdoc.  foo_p turns into foo?, etc.

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

I just don't buy the argument about code readability.  Function
definitions *very* commonly exploit macros (see my research paper on an
empirical study of C preprocessor use) and better-than-novice programs
will only look twice before figuring out what's going on.

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

Ugh... please *please* look into the disappearing act your words do.

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

That's the main reason I even proposed the change before touching all
the source. 

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

I'll be making the change next weekend, I expect.  I appreciate the
feedback from you and everyone.  Thanks!

Greg