[Guile-commits] 03/06: Add documentation on embedded procedure properties

[Andy Wingo]

wingo pushed a commit to branch main
in repository guile.

commit 305b2fa70c81372c0ef1983e5aada9bee9ec403b
Author: Andy Wingo <wingo@pobox.com>
AuthorDate: Thu Jun 20 13:54:31 2024 +0200

    Add documentation on embedded procedure properties
    
    * doc/ref/api-procedures.texi (Procedure Properties): Document inline
    procedure properties.
---
 doc/ref/api-procedures.texi | 95 ++++++++++++++++++++++++++++-----------------
 1 file changed, 59 insertions(+), 36 deletions(-)

diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi
index 2684d8575..65ae2dbb1 100644
--- a/doc/ref/api-procedures.texi
+++ b/doc/ref/api-procedures.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010,
-@c   2011, 2012, 2013  Free Software Foundation, Inc.
+@c   2011, 2012, 2013, 2024  Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @node Procedures
@@ -697,11 +697,6 @@ name of a procedure is information not for the procedure, 
but about
 the procedure. This meta-information can be accessed via the procedure
 properties interface.
 
-The first group of procedures in this meta-interface are predicates to
-test whether a Scheme object is a procedure, or a special procedure,
-respectively.  @code{procedure?} is the most general predicates, it
-returns @code{#t} for any kind of procedure.
-
 @rnindex procedure?
 @deffn {Scheme Procedure} procedure? obj
 @deffnx {C Function} scm_procedure_p (obj)
@@ -711,7 +706,8 @@ Return @code{#t} if @var{obj} is a procedure.
 @deffn {Scheme Procedure} thunk? obj
 @deffnx {C Function} scm_thunk_p (obj)
 Return @code{#t} if @var{obj} is a procedure that can be called with
-zero arguments.
+zero arguments.  @xref{Compiled Procedures}, to get more information
+on what arguments a procedure will accept.
 @end deffn
 
 @cindex procedure properties
@@ -719,51 +715,78 @@ Procedure properties are general properties associated 
with
 procedures. These can be the name of a procedure or other relevant
 information, such as debug hints.
 
-@deffn {Scheme Procedure} procedure-name proc
-@deffnx {C Function} scm_procedure_name (proc)
-Return the name of the procedure @var{proc}
+The most general way to associate a property of a procedure is
+programmatically:
+
+@deffn {Scheme Procedure} procedure-property proc key
+@deffnx {C Function} scm_procedure_property (proc, key)
+Return the property of @var{proc} with name @var{key}, or @code{#f} if
+not found.
+@end deffn
+
+@deffn {Scheme Procedure} set-procedure-property! proc key value
+@deffnx {C Function} scm_set_procedure_property_x (proc, key, value)
+Set @var{proc}'s property named @var{key} to @var{value}.
 @end deffn
 
-@deffn {Scheme Procedure} procedure-source proc
+However, there is a more efficient interface that allows constant
+properties to be embedded into compiled binaries in a way that does
+not incur any overhead until someone asks for the property: initial
+non-tail elements of the body of a lambda expression that are literal
+vectors of pairs are interpreted as declaring procedure properties.
+This is easiest to see with an example:
+
+@example
+(define proc
+  (lambda args
+    #((a . "hey") (b . "ho")) ;; procedure properties!
+    42))
+(procedure-property proc 'a) ; @result{} "hey"
+(procedure-property proc 'b) ; @result{} "ho"
+@end example
+
+There is a shorthand for declaring the @code{documentation} property,
+which is a literal string instead of a literal vector:
+
+@example
+(define proc
+  (lambda args
+    "This is a docstring."
+    42))
+(procedure-property proc 'documentation)
+;; @result{} "This is a docstring."
+@end example
+
+Calling @code{procedure-property} with a key of @code{documentation}
+is exactly the same as calling @code{procedure-documentation}.
+Similarly, @code{procedure-name} is the same as the @code{name}
+procedure property, and @code{procedure-source} is for the
+@code{source} property.
+
+@deffn {Scheme Procedure} procedure-name proc
+@deffnx {C Function} scm_procedure_name (proc)
+@deffnx {Scheme Procedure} procedure-source proc
 @deffnx {C Function} scm_procedure_source (proc)
-Return the source of the procedure @var{proc}. Returns @code{#f} if
-the source code is not available.
+@deffnx {Scheme Procedure} procedure-documentation proc
+@deffnx {C Function} scm_procedure_documentation (proc)
+Return the value of the @code{name}, @code{source}, or
+@code{documentation} property for @var{proc}, or @code{#f} if no
+property is set.
 @end deffn
 
+One can also work on the entire set of procedure properties.
+
 @deffn {Scheme Procedure} procedure-properties proc
 @deffnx {C Function} scm_procedure_properties (proc)
 Return the properties associated with @var{proc}, as an association
 list.
 @end deffn
 
-@deffn {Scheme Procedure} procedure-property proc key
-@deffnx {C Function} scm_procedure_property (proc, key)
-Return the property of @var{proc} with name @var{key}.
-@end deffn
-
 @deffn {Scheme Procedure} set-procedure-properties! proc alist
 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
 Set @var{proc}'s property list to @var{alist}.
 @end deffn
 
-@deffn {Scheme Procedure} set-procedure-property! proc key value
-@deffnx {C Function} scm_set_procedure_property_x (proc, key, value)
-In @var{proc}'s property list, set the property named @var{key} to
-@var{value}.
-@end deffn
-
-@cindex procedure documentation
-Documentation for a procedure can be accessed with the procedure
-@code{procedure-documentation}.
-
-@deffn {Scheme Procedure} procedure-documentation proc
-@deffnx {C Function} scm_procedure_documentation (proc)
-Return the documentation string associated with @code{proc}.  By
-convention, if a procedure contains more than one expression and the
-first expression is a string constant, that string is assumed to contain
-documentation for that procedure.
-@end deffn
-
 
 @node Procedures with Setters
 @subsection Procedures with Setters