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:21:33 +0200 Message-ID: References: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary=e89a8ff24d9bd8327c04e3bd7e27 X-Trace: ger.gmane.org 1376302940 10512 80.91.229.3 (12 Aug 2013 10:22:20 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 12 Aug 2013 10:22: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:22: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 1V8pGY-0004db-GT for guile-user@m.gmane.org; Mon, 12 Aug 2013 12:22:22 +0200 Original-Received: from localhost ([::1]:33725 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V8pGY-0002Mp-3a for guile-user@m.gmane.org; Mon, 12 Aug 2013 06:22:22 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50340) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V8pGL-0002LK-Gy for guile-user@gnu.org; Mon, 12 Aug 2013 06:22:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V8pGF-0002LK-Te for guile-user@gnu.org; Mon, 12 Aug 2013 06:22:09 -0400 Original-Received: from mail-vb0-x235.google.com ([2607:f8b0:400c:c02::235]:53047) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V8pGF-0002LB-OL; Mon, 12 Aug 2013 06:22:03 -0400 Original-Received: by mail-vb0-f53.google.com with SMTP id i3so5485075vbh.40 for ; Mon, 12 Aug 2013 03:22:03 -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=u+I6m8uI+TGolFeTQulhjVAP/EWrvIiH2WpCVkjkQCE=; b=I9gIDEnHf06C+ovqYTNDqi1enzkoRGkFFYk16wlW3hwsdjR4aL4dk2CDS3h9PRhyE5 r17ZNqRAzwCQD20poYygWv7ioUXT5VCwQ6Bc6nhz7NXwyQCqos9C0EnTSh1OykAvpWOq 04POVXMgeEaqlAZvPHIX4jmYMCXKfVuQIx9kM5XRbDOh3jFgA7jzmEHc+SEWvXKq+PZx 3SS2x5P8+wGBfMHnRaIwRIYWOsxzdnGvB9dxgS8jJWeYcGzflpfOj7dlzEwI2KK3fYAc O6dza9bXjTKXU7Q2h3+H5ZOGBwn6O34o34Q1cbZpCgkNXmd+LhrnmJWitxVW173DA/oF ASQA== X-Received: by 10.52.103.35 with SMTP id ft3mr9764099vdb.5.1376302923262; Mon, 12 Aug 2013 03:22:03 -0700 (PDT) Original-Received: by 10.220.91.69 with HTTP; Mon, 12 Aug 2013 03:21:33 -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::235 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:10622 gmane.lisp.guile.devel:16554 Archived-At: --e89a8ff24d9bd8327c04e3bd7e27 Content-Type: text/plain; charset=UTF-8 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). --e89a8ff24d9bd8327c04e3bd7e27 Content-Type: text/x-chdr; charset=US-ASCII; name="procedure-doc.h" Content-Disposition: attachment; filename="procedure-doc.h" Content-Transfer-Encoding: base64 X-Attachment-Id: f_hk9j6ga50 Ly9JIHJlZGVmaW5lZCB0aGUgbWFjcm9zIFNDTV9ERUZJTkUgYW5kIFNDTV9QUk9DIAovL2FzIFND TV9ERUZJTkVEIGFuZCBTQ01fUFJPQ0QKI2RlZmluZSBTQ01fREVGSU5FRChGTkFNRSwgUFJJTU5B TUUsIFJFUSwgT1BULCBWQVIsIEFSR0xJU1QsIERPQ1NUUklORykgXApTQ01fU05BUkZfSEVSRShc CnN0YXRpYyBjb25zdCBjaGFyIHNfICMjIEZOQU1FIFtdID0gUFJJTU5BTUU7IFwKU0NNIEZOQU1F IEFSR0xJU1RcCilcClNDTV9TTkFSRl9JTklUKFwKICBzY21fcHJvY2VkdXJlX2RvY3VtZW50YXRp b25feAlcCiAgICAoc2NtX2NfZGVmaW5lX2dzdWJyIChzXyAjIyBGTkFNRSwgUkVRLCBPUFQsIFZB UiwJCVwKCQkJIChTQ01fRlVOQ19DQVNUX0FSQklUUkFSWV9BUkdTKSBGTkFNRSksCVwKICAgICBz Y21fc3RyMnN0cmluZyhET0NTVFJJTkcpKTsgXAopXAovL1NDTV9TTkFSRl9ET0NTKHByaW1pdGl2 ZSwgRk5BTUUsIFBSSU1OQU1FLCBBUkdMSVNULCBSRVEsIE9QVCwgVkFSLCBET0NTVFJJTkcpCgoj ZGVmaW5lIFNDTV9QUk9DRChSQU5BTUUsIFNUUiwgUkVRLCBPUFQsIFZBUiwgQ0ZOLERPQ1NUUklO RykJXApTQ01fU05BUkZfSEVSRShzdGF0aWMgY29uc3QgY2hhciBSQU5BTUVbXT1TVFIpIAkJCVwK U0NNX1NOQVJGX0lOSVQoc2NtX3Byb2NlZHVyZV9kb2N1bWVudGF0aW9uX3gJCQlcCiAgKHNjbV9j X2RlZmluZV9nc3ViciAoUkFOQU1FLCBSRVEsIE9QVCwgVkFSLAkJCVwKCQkgICAgIChTQ01fRlVO Q19DQVNUX0FSQklUUkFSWV9BUkdTKSBDRk4pLAlcCiAgIHNjbV9zdHIyc3RyaW5nKERPQ1NUUklO RykpKQoKLy8gYWRkZWQgYSBwcm9jZWR1cmUgcHJvY2VkdXJlLWRvY3VtZW50YXRpb24hCnN0YXRp YyBTQ00gc2NtX2RvY3VtZW50YXRpb247ClNDTV9QUk9DRChzX3Byb2NlZHVyZV9kb2N1bWVudGF0 aW9uLCAicHJvY2VkdXJlLWRvY3VtZW50YXRpb24hIiwKCSAgMSwwLDAsIHNjbV9wcm9jZWR1cmVf ZG9jdW1lbnRhdGlvbl94LAoJICAiKHByb2NlZHVyZS1kb2N1bWVudGF0b24hIHByb2Mge2RvY30p XG4iCgkgICJSZXR1cm5zIG9yIHNldHMgdGhlIGRvYyBzdHJpbmcgYXNzb2NpYXRlZCB3aXRoIEBj b2Rle3Byb2N9LiIpOwpTQ00gc2NtX3Byb2NlZHVyZV9kb2N1bWVudGF0aW9uX3goU0NNIHByb2Ms IFNDTSBkb2MpCnsKICBTQ00gY29kZSxvcmlnOwogIFNDTV9BU1NFUlQgKHNjbV9pc190cnVlIChz Y21fcHJvY2VkdXJlX3AgKHByb2MpKSwKCSAgICAgIHByb2MsIFNDTV9BUkcxLCBzX3Byb2NlZHVy ZV9kb2N1bWVudGF0aW9uKTsKICBzd2l0Y2ggKFNDTV9UWVA3IChwcm9jKSkKICAgIHsKICAgIGNh c2Ugc2NtX3Rjc19jbG9zdXJlczoKICAgICAgY29kZSA9IFNDTV9DTE9TVVJFX0JPRFkgKHByb2Mp OwogICAgICBpZiAoc2NtX2lzX251bGwgKFNDTV9DRFIgKGNvZGUpKSkKCXJldHVybiBTQ01fQk9P TF9GOwogICAgICBvcmlnID0gU0NNX0NBUiAoY29kZSk7CiAgICAgIGlmIChzY21faXNfc3RyaW5n IChvcmlnKSkgewoJaWYgKHNjbV9pc19zdHJpbmcgKGRvYykpIHsKCSAgU0NNX1NFVENBUihjb2Rl LGRvYyk7CgkgIHJldHVybiBkb2M7Cgl9CglyZXR1cm4gb3JpZzsKICAgICAgfQogICAgICBlbHNl CglyZXR1cm4gU0NNX0JPT0xfRjsKICAgICAgYnJlYWs7CiAgICBkZWZhdWx0OgogICAgICBpZiAo c2NtX2lzX3N0cmluZyAoZG9jKSkgewoJc2NtX3NldF9wcm9jZWR1cmVfcHJvcGVydHlfeChwcm9j LHNjbV9kb2N1bWVudGF0aW9uLGRvYyk7CglyZXR1cm4gZG9jOwogICAgICB9CiAgICAgIGVsc2UK CXJldHVybiBzY21fcHJvY2VkdXJlX3Byb3BlcnR5KHByb2Msc2NtX2RvY3VtZW50YXRpb24pOwog ICAgICBicmVhazsKICAgIH0KICByZXR1cm4gU0NNX0JPT0xfRjsKfQoKLy9hbmQgdG8gdGhlIGlu aXQgcHJvY2VkdXJlCi8vICBzY21fZG9jdW1lbnRhdGlvbj1zY21fZnJvbV9sb2NhbGVfc3ltYm9s KCJkb2N1bWVudGF0aW9uIik7Ci8vICAjaW5jbHVkZSAieW91cm1vZHVsZS54Igo= --e89a8ff24d9bd8327c04e3bd7e27--