I found an easy way to set documentation for closures and procedures.
I wrote this to guile-user earlier but send it to guile-devel as well
as it may be of interest.
On Fri, Aug 9, 2013 at 8:06 PM, Roland Orre <roland.o...@gmail.com> wrote:
>
> There is no simple way to set procedure-documentation in guile.
> For some years I've done it in the module's scheme description like
> (set-procedure-property! proc 'documentation "help text")
>
>
> but this is quite hard to maintain, and what seems to be the standard way
> (looking at libguile) SCM_DEFINE is too complicted and tedious.
>
I attach the code part as a file also, in case someone wants to use it.
OK, I solved it like this,
//I redefined the macros SCM_DEFINE and SCM_PROC
//as SCM_DEFINED and SCM_PROCD
#define SCM_DEFINED(FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING) \
SCM_SNARF_HERE(\
static const char s_ ## FNAME [] = PRIMNAME; \
SCM FNAME ARGLIST\
)\
SCM_SNARF_INIT(\
scm_procedure_documentation_x \
(scm_c_define_gsubr (s_ ## FNAME, REQ, OPT, VAR, \
(SCM_FUNC_CAST_ARBITRARY_ARGS) FNAME), \
scm_str2string(DOCSTRING)))
//SCM_SNARF_DOCS(primitive, FNAME, PRIMNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING)
#define SCM_PROCD(RANAME, STR, REQ, OPT, VAR, CFN,DOCSTRING) \
SCM_SNARF_HERE(static const char RANAME[]=STR) \
SCM_SNARF_INIT(scm_procedure_documentation_x \
(scm_c_define_gsubr (RANAME, REQ, OPT, VAR, \
(SCM_FUNC_CAST_ARBITRARY_ARGS) CFN), \
scm_str2string(DOCSTRING)); \
)
// added a procedure procedure-documentation!
static SCM scm_documentation;
SCM_PROCD(s_procedure_documentation, "procedure-documentation!",
1,0,0, scm_procedure_documentation_x,
"(procedure-documentaton! proc {doc})\n"
"Returns or sets the doc string associated with @code{proc}.");
SCM scm_procedure_documentation_x(SCM proc, SCM doc)
{
SCM code,orig;
SCM_ASSERT (scm_is_true (scm_procedure_p (proc)),
proc, SCM_ARG1, s_procedure_documentation);
switch (SCM_TYP7 (proc))
{
case scm_tcs_closures:
code = SCM_CLOSURE_BODY (proc);
if (scm_is_null (SCM_CDR (code)))
return SCM_BOOL_F;
orig = SCM_CAR (code);
if (scm_is_string (orig)) {
if (scm_is_string (doc)) {
SCM_SETCAR(code,doc);
return doc;
}
return orig;
}
else
return SCM_BOOL_F;
break;
default:
if (scm_is_string (doc)) {
scm_set_procedure_property_x(proc,scm_documentation,doc);
return doc;
}
else
return scm_procedure_property(proc,scm_documentation);
break;
}
return SCM_BOOL_F;
}
//and to the init procedure
// scm_documentation=scm_from_locale_symbol("documentation");
// #include "yourmodule.x"
This results in the following definition in the .x file
scm_procedure_documentation_x (scm_c_define_gsubr
(s_procedure_documentation, 1, 0, 0, (SCM (*)())
scm_procedure_documentation_x),
scm_str2string("(procedure-documentaton! proc {doc}\n" "Returns or
sets the doc string associated with @code{proc}.")); ;
and of course similar for SCM_DEFINED, but I've defined most of my
procedures with SCM_PROC anyway as the documentation hadn't been
easy to get working. I also consider SCM_PROCD the cleaner
solution, as I do not need to do one #define #undef for every procedure,
and I can clearly see what arguments the procdure takes.
I intended to generalise it to a a similar object-documentation!
later with support for doc on file/database etc, but now I can
finally get all my old C-routines documented without having the
info in different files (the module init file).
//I redefined the macros SCM_DEFINE and SCM_PROC
//as SCM_DEFINED and SCM_PROCD
#define SCM_DEFINED(FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING) \
SCM_SNARF_HERE(\
static const char s_ ## FNAME [] = PRIMNAME; \
SCM FNAME ARGLIST\
)\
SCM_SNARF_INIT(\
scm_procedure_documentation_x \
(scm_c_define_gsubr (s_ ## FNAME, REQ, OPT, VAR, \
(SCM_FUNC_CAST_ARBITRARY_ARGS) FNAME), \
scm_str2string(DOCSTRING)); \
)\
//SCM_SNARF_DOCS(primitive, FNAME, PRIMNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING)
#define SCM_PROCD(RANAME, STR, REQ, OPT, VAR, CFN,DOCSTRING) \
SCM_SNARF_HERE(static const char RANAME[]=STR) \
SCM_SNARF_INIT(scm_procedure_documentation_x \
(scm_c_define_gsubr (RANAME, REQ, OPT, VAR, \
(SCM_FUNC_CAST_ARBITRARY_ARGS) CFN), \
scm_str2string(DOCSTRING)))
// added a procedure procedure-documentation!
static SCM scm_documentation;
SCM_PROCD(s_procedure_documentation, "procedure-documentation!",
1,0,0, scm_procedure_documentation_x,
"(procedure-documentaton! proc {doc})\n"
"Returns or sets the doc string associated with @code{proc}.");
SCM scm_procedure_documentation_x(SCM proc, SCM doc)
{
SCM code,orig;
SCM_ASSERT (scm_is_true (scm_procedure_p (proc)),
proc, SCM_ARG1, s_procedure_documentation);
switch (SCM_TYP7 (proc))
{
case scm_tcs_closures:
code = SCM_CLOSURE_BODY (proc);
if (scm_is_null (SCM_CDR (code)))
return SCM_BOOL_F;
orig = SCM_CAR (code);
if (scm_is_string (orig)) {
if (scm_is_string (doc)) {
SCM_SETCAR(code,doc);
return doc;
}
return orig;
}
else
return SCM_BOOL_F;
break;
default:
if (scm_is_string (doc)) {
scm_set_procedure_property_x(proc,scm_documentation,doc);
return doc;
}
else
return scm_procedure_property(proc,scm_documentation);
break;
}
return SCM_BOOL_F;
}
//and to the init procedure
// scm_documentation=scm_from_locale_symbol("documentation");
// #include "yourmodule.x"
