Re: Scwm docstrings change

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

mstachow@alum.mit.edu writes:

> "Greg J. Badros" wrote:
> > 
> > I just implemented the change to use literal strings as the final
> > argument to the SCWM_*PROC macros instead of using an embedded comment
> > following the complete macro invocation.  E.g., whereas Scwm used to use
> > this:
> > 
> > SCWM_PROC(X_store_bytes, "X-store-bytes", 1, 0, 0,
> >           (SCM string))
> > /** Set the cut buffer to STRING by calling XStoreBytes. */
> > #define FUNC_NAME s_X_store_bytes
> > {
> >   VALIDATE_ARG_STR_NEWCOPY(1,string,sz);
> >  // body removed
> > }
> > #undef FUNC_NAME
> > 
> > we now use:
> > 
> > SCWM_PROC(X_store_bytes, "X-store-bytes", 1, 0, 0,
> >           (SCM string),
> > "Set the cut buffer to STRING by calling XStoreBytes.")
> > #define FUNC_NAME s_X_store_bytes
> > {
> >   VALIDATE_ARG_STR_NEWCOPY(1,string,sz);
> >  // body removed
> > }
> > #undef FUNC_NAME
> > 
> 
> I think this is a good change. It has the additional benefit that it's
> impossible not to document a procedure - you could include an empty
> docstring
> parameter, but you'd have to go out of your way to do so.
> 
> However, for Guile I don't think we should change SCM_PROC to include
> the C
> argument list and to expand

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?

> Also, for Guile it will be necessary to add a documentation string
> argument
> to a few other macros, such as SCM_PROC1, SCM_GPROC, SCM_GPROC1, and
> SCM_SYNTAX.

Sure.  There's more than just SCWM_PROC for Scwm, but they work the same 
way.

> Finally, a few procedures in Guile are declared by manually calling
> functions such as make_subr() or make_subr_opt() for various reasons,
> so there should be a way to document a procedure that is not created
> with one of the macros.

This is something we currently don't handle exceptionally well in Scwm,
but there clearly are plenty of solutions that can be added
independently later.

Greg