From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Roland Orre Newsgroups: gmane.lisp.guile.user,gmane.lisp.guile.devel Subject: Re: Easiest way to set procedure-documentation? Date: Mon, 12 Aug 2013 12:24:34 +0200 Message-ID: References: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: ger.gmane.org 1376303120 12453 80.91.229.3 (12 Aug 2013 10:25:20 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 12 Aug 2013 10:25:20 +0000 (UTC) Cc: guile-devel@gnu.org To: guile-user@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Mon Aug 12 12:25:23 2013 Return-path: Envelope-to: guile-user@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1V8pJS-00078d-6j for guile-user@m.gmane.org; Mon, 12 Aug 2013 12:25:22 +0200 Original-Received: from localhost ([::1]:34291 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V8pJR-000335-QI for guile-user@m.gmane.org; Mon, 12 Aug 2013 06:25:21 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:51061) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V8pJF-000307-KD for guile-user@gnu.org; Mon, 12 Aug 2013 06:25:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V8pJA-0003q5-SW for guile-user@gnu.org; Mon, 12 Aug 2013 06:25:09 -0400 Original-Received: from mail-vb0-x234.google.com ([2607:f8b0:400c:c02::234]:49368) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V8pJA-0003oe-Ov; Mon, 12 Aug 2013 06:25:04 -0400 Original-Received: by mail-vb0-f52.google.com with SMTP id f12so5606348vbg.11 for ; Mon, 12 Aug 2013 03:25:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=PQlsNRXcAqaXNdmRUbYH6hVVghfP6vDrvWU/MSPoyWc=; b=ZXKo9kyFg2HbloxBs8VoVglgY3Pi0owopeBWvuFOXEA//ye2oxISLm01JO9iRXsgA9 5l5UTF/H4jmLhs82UyxBxODRei/UCdGvZ0iN/b0pSxHq/VnOO+nAwY83rxBVkmMrNLUz LNuxAYIMoSY0k3ruot2/XGXyKK24gBrQwGeCn+yoIcqGV5NUtfXwrB4/mY2Y01jk+BkQ i7OsbydmBQUrh/oTwiEKLvGqy9MH0th1lxfLSlCS7GD3YJjV7qKOpTGbBbE6+epODcC7 4kt2AZkfJfYxica/B/PgvGKWrUVg2bQkUYZk8rnS26TwA4uIkoWSo3Bg1SKQ4U34H2EQ I+Xw== X-Received: by 10.52.231.97 with SMTP id tf1mr4999845vdc.15.1376303104401; Mon, 12 Aug 2013 03:25:04 -0700 (PDT) Original-Received: by 10.220.91.69 with HTTP; Mon, 12 Aug 2013 03:24:34 -0700 (PDT) In-Reply-To: X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2607:f8b0:400c:c02::234 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Original-Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.user:10623 gmane.lisp.guile.devel:16555 Archived-At: 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 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 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).