Re: Scwm docstrings change

[mstachow at alum dot mit dot edu]

"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

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.

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.

 - Maciej