Re: Scwm docstrings change

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

mstachow@alum.mit.edu writes:

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

I am unconvinced.  The average C programmer shouldn't be reading the
Guile source anyway.  It's far more important that the invariants
between the two parts be clearly intimately tied (and statically
checked, though separating them would only complicate, not eliminate,
the static checking that scwmdoc does). 

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

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.

It's a historical necessity that people read the Guile source code
because of the lack of documentation.  With the docstrings, the average
user will not be reading Guile source, and those that do can figure out
what's going on pretty damn easily (especially with decent developer
getting-started documentation).

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

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.  

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.

Greg