Re: Scwm docstrings change

[mstachow at alum dot mit dot edu]

"Greg J. Badros" wrote:
> 

> Obviously I disagree;  I think it is essential that we get the software
> engineering checks that Scwm's documentation extractor gives us.  It
> looks like you've got a snipped line, though, so perhaps you have a good
> counterargument that disappeared into /dev/null?
> 

Yes I did, at least I think it's a good one. The problem is that

SCM_PROC(foo_proc,"foo-proc",1,0,0, (SCM bar),
	 "Documentation for foo_proc")
{
	/* Function body .... */
}

will be a lot more initially confusing to a programmer who is familiar
with C but not with Guile than

SCM_PROC(foo_proc,"foo-proc",1,0,0, "Documentation for foo_proc");

SCM foo_proc (SCM bar)
{
	/* Function body .... */
}

It is much more immediately clear that a function is being declared.
Although it is legal for a macro to expand to just about anything,
I have never seen it expand to a function declaration without
the body. So without being immediately familiar ahead of time
with the conventions, the average C programmer would be really
confused by this. This is exacerbated by the fact that function
declaration syntax and macro call syntax are rather similar.

In Scwm it is fair to ask people to be very familiar with the code
conventions before delving in, since the only likely reason to want
to do this is to hack Scwm. (Actually, it's become clear of late
that a lot of people also look at Scwm code to steal code for their
own applications - I am not sure whether this should be further 
encouraged, or the relevant code should be put into a library, either
libguile or some add-on). But in the case of Guile, many application
developers will want to look at the library code to gain a better
understanding of how various things work, or out of curiosity, or
because they want to add a feature. Thus, the code should have the
lowest barrier to entry possible.

I also do not think that doing it this way makes it impossible to
ensure that the argument list corresponds to the numbers of fixed,
optional and rest arguments specified, or that all formal parameters
are documented. The extractor would just have to be smarter and find
the function prototype as well as the call to SCM_PROC. This may be
a bit more work, but I believe it is worth it for the sake of the
greater code readability.

 - Maciej