Re: Easiest way to set procedure-documentation?

Re: Easiest way to set procedure-documentation?

[Roland Orre]

[-- Attachment #1: Type: text/plain, Size: 3550 bytes --]

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.orre@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).

[-- Attachment #2: procedure-doc.h --]
[-- Type: text/x-chdr, Size: 1985 bytes --]

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

Re: Easiest way to set procedure-documentation?

[Roland Orre]

Sorry, the declaration should be this of course

SCM_PROCD(s_procedure_documentation, "procedure-documentation!",
           1,1,0, scm_procedure_documentation_x,
           "(procedure-documentaton! proc {doc})\n"
           "Returns or sets the doc string associated with @code{proc}.");


On Mon, Aug 12, 2013 at 12:21 PM, Roland Orre <roland.orre@gmail.com> wrote:
> 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.orre@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).