Re: docstrings in Guile!

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

Michael Livshin <mlivshin@bigfoot.com> writes:

<snip>
> P.S.  for a long time now, I wonder how you choose to name things.  in
> SCWM, there is plenty of things named like 'do-this-and-also-do-that-not-
> forgetting-that' (ok, I'm exaggerating).

Well, it's not *that* bad! :-) There are some issues with Scwm and
deciding how to customize behaviour that I basically punted on and may
have influenced the especially long names.  E.g., there is
animated-deiconify, deiconify, animated-deiconify-to-current-viewport,
etc.  Choosing a behaviour is a simple matter of changing the named
procedure *but* there is no way to influence the behaviour of a module
that, say, uses "deiconify" w/o changing that module.  I know there are
solutions out there, but they all seem ugly to me.

> I somehow don't feel comfortable with 'guile-doc-snarf', for instance.
> I mean, it's a misleading name, I first got it to mean "snarf the
> docstrings".  but it snarfs everything, so perhaps 'guile-snarf'
> really is better, even if it's old and boring ;).

Yep; it's a better name but was already taken.  I'm anticipating
blasting guile-snarf later 

> oh, and 'touch --date=<date> <fname>' isn't portable.  'touch -t
> <date> <fname>' should be, though.

Okay, switched.

> oh, and scm_ in scm_validate is redundant.

Not in the context of scwm-- I already had a "validate.h" with it, so I
wanted to avoid (my own) confusion.  I'll rename after I fold the
SCM_VALIDATE_* into the appropriate header files (the macros that remain 
might have a better conceptual name than validation by that point).

> but the above are, of course, tiny nitpicks.  great work, thanks.
> it's psychological impact is probably pretty big, too.

That's what we've gotta bet on... at least to me the code is infinitely
more readable given the simplified argument validation.  Also it's a lot 
less intimidating to work on the documentation when the code is right
there and you know the documentation makes a difference immediately.

One remaining annoyance that I did not yet fix... lots of this pattern:

SCM_NIMP(x) && SCM_FOOP(x)

I don't think that there is that big of a performance win by not having
the SCM_FOOP's check SCM_NIMP (there are some places where the SCM_NIMP
is factored out into an earlier test that affects several branches).

I think we should fold the SCM_NIMP macro test into SCM_FOOP macro
definitions, and add a new SCM_F_FOOP (for *F*ast foop) or
SCM_SLOPPY_FOOP for the cases where we really want that test omitted.
Then things work right away (perhaps with a non-noticeable performance
degradation), and where performance *really* counts (based on profiling) 
we can switch to SCM_SLOPPY_FOOP.  Elsewhere we just eliminate the
SCM_NIMP eyesore.

Comments (before I just go run with this idea!)?

Greg