Easiest way to set procedure-documentation?

Easiest way to set procedure-documentation?

[Roland Orre]

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

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)
is too complicated, so what I did was to redefine the SCM_DEFINE macro
and add a line for setting procedure doc from the included .x file as well.

But, as I can see there is no primitive for setting the procedure doc, only
reading it.
Is it safe to take the  procedure procedure-documentation
and modify the CAR where it expects the doc string to be found?

Of course I can do it by using set-procedure-property from C but I thought
there may be a more direct way.

[-- Attachment #2: Type: text/html, Size: 856 bytes --]

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

Re: Easiest way to set procedure-documentation?

[Andy Wingo]

Hi Roland,

If you want to give documentation to procedures defined in C with
SCM_DEFINE, you can associate an external documentation file with the
module.  See
http://git.savannah.gnu.org/cgit/guile-cairo.git/tree/cairo/Makefile.am
and http://git.savannah.gnu.org/cgit/guile-cairo.git/tree/cairo.scm.

A patch to the Guile manual would be wonderful :-)

Andy
-- 
http://wingolog.org/

Re: Easiest way to set procedure-documentation?

[Roland Orre]

Thanks for the hint Andy. However, for now I've made a patch of
SCM_DEFINE and SCM_PROC, actually as SCM_PUBLIC_DEFINE as well as
SCM_PUBLIC_PROC (to not collide with SCM_DEFINE_PUBLIC) as well as
SCM_PUBLIC_CONST and SCM_PUBLIC_SUBR (same as PROC but with doc and
C-parameters (as the DEFINE macro) for generation of library link
references) and SCM_PUBLIC_SYNTAX which adds procedure or object
documentation as well as automatic c-export of symbols and generation
of include files to be included by other modules linking to other user
modules on the fly from the snarf preprocessing.
The external file is great when development has stabilized and docs,
parameters and such do not change often/much, but with hundreds of
routines and plenty of modules it is hard to maintain same info at
many places at once.
My modified snarf macros generate a module.xp which contains extern
declaration of the routines and constants apart from the module.x as
well as a libmodule.h, where one part is static (libmodule.hin) and
the rest generated from the macros. I'll send them up for evaluation
soon if you consider them interesting.
I also added a routine load-module-library where you just give the init entry as
(load-module-library "scm_init_user")
which uses the module name to load libuser.so  so the file, in this
case, user.scm which is loaded when  doing (use-modules (user))
basically only needs to contain that single line (load-module-library
"scm_init_user") and all exports are made automatically (as when using
in SCM_DEFINE_PUBLIC, but what was missing was similar for PROC,SYNTAX
and CONST).

On Sat, Sep 7, 2013 at 11:42 AM, Andy Wingo <wingo@pobox.com> wrote:
> Hi Roland,
>
> If you want to give documentation to procedures defined in C with
> SCM_DEFINE, you can associate an external documentation file with the
> module.  See
> http://git.savannah.gnu.org/cgit/guile-cairo.git/tree/cairo/Makefile.am
> and http://git.savannah.gnu.org/cgit/guile-cairo.git/tree/cairo.scm.
>
> A patch to the Guile manual would be wonderful :-)
>
> Andy
> --
> http://wingolog.org/