From 158a845d0b288de44efb7097ffb754a0f6dc56ff Mon Sep 17 00:00:00 2001
From: Liam Healy <liam@thinkpad.local>
Date: Sat, 27 Nov 2010 12:16:58 -0500
Subject: [PATCH] Added comments for maref

---
 data/both.lisp        | 18 +++++++++++++-----
 init/funcallable.lisp | 14 +++++++-------
 2 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/data/both.lisp b/data/both.lisp
index 0b8f5036..31c23f45 100644
--- a/data/both.lisp
+++ b/data/both.lisp
@@ -1,6 +1,6 @@
 ;; Functions for both vectors and matrices.
 ;; Liam Healy 2008-04-26 20:48:44EDT both.lisp
-;; Time-stamp: <2010-11-24 23:26:40EST both.lisp>
+;; Time-stamp: <2010-11-25 09:31:17EST both.lisp>
 ;;
 ;; Copyright 2008, 2009, 2010 Liam M. Healy
 ;; Distributed under the terms of the GNU General Public License
@@ -86,11 +86,18 @@
 ;;; access components, we use these macros which expand to gsl_*_get
 ;;; and gsl_*_set.
 
+;;; It's unlikely users will need maref directly, because when using
+;;; the GSL library, we use the grid functions to get elements.  The
+;;; main use in the GSL library is user-defined callbacks (e.g. in
+;;; solve-minimize-fit) when scalarsp = T is specified; in that case
+;;; the generated wrapper function includes maref.  However, if
+;;; another foreign library which used the GSL library provided an
+;;; mpointer, the maref macro saves the time of creating an object
+;;; around it.
 (export 'maref)
 
-(eval-when (:compile-toplevel :load-toplevel :execute)
 (defun access-value-int (mpointer class-name value indices)
-  "Access the GSL array value from the mpointer.  If value is not nil,
+  "Create a form to access the GSL array value from the mpointer.  If value is not nil,
    set the value; otherwise, get the value."
   ;; (access-value-int 'ptr 'grid:vector-unsigned-byte-16 45 '(3))
   ;; (FOREIGN-FUNCALL "gsl_vector_ushort_set" :POINTER PTR SIZET 3 :UNSIGNED-SHORT 45 :VOID)
@@ -113,10 +120,11 @@
       ,@(when matrixp (list 'sizet (second indices)))
       ,(grid:cl-cffi element-type)
       ,@(when value `(,value :void)))))
-)
 
 (defmacro maref (mpointer class-name &rest indices)
-  "Get or set the array element from the GSL pointer."
+  "Get or set (setf maref) the array element from the GSL mpointer.
+   The class-name is the specific subclass name of
+   grid:foreign-array."
   (access-value-int mpointer class-name nil indices))
 
 (defmacro set-maref (mpointer class-name &rest indices-value)
diff --git a/init/funcallable.lisp b/init/funcallable.lisp
index 86b0a98f..3ef4e7b0 100644
--- a/init/funcallable.lisp
+++ b/init/funcallable.lisp
@@ -1,6 +1,6 @@
 ;; Generate a lambda that calls the user function; will be called by callback.
 ;; Liam Healy 
-;; Time-stamp: <2010-11-24 22:01:05EST funcallable.lisp>
+;; Time-stamp: <2010-11-25 09:09:40EST funcallable.lisp>
 ;;
 ;; Copyright 2009, 2010 Liam M. Healy
 ;; Distributed under the terms of the GNU General Public License
@@ -84,13 +84,13 @@
 ;;;;****************************************************************************
 
 (defun reference-foreign-element
-    (foreign-variable-name linear-index argspec dimension-values)
-  "Form to reference, for getting or setting, the element of a foreign
-   array, or a scalar."
+    (foreign-pointer-name linear-index argspec dimension-values)
+  "Create the form to reference the element of a foreign
+   array, or a scalar, for getting or setting."
   (if (parse-callback-argspec argspec 'dimensions)
       (if (eql (parse-callback-argspec argspec 'array-type) :foreign-array)
 	  `(maref
-	    ,foreign-variable-name
+	    ,foreign-pointer-name
 	    ,(grid:data-class-name
 	      (length (value-from-dimensions argspec dimension-values))
 	      (grid:cffi-cl (parse-callback-argspec argspec 'element-type)))
@@ -98,11 +98,11 @@
 	       (affi:make-affi (value-from-dimensions argspec dimension-values))
 	       linear-index))
 	  `(cffi:mem-aref
-	    ,foreign-variable-name
+	    ,foreign-pointer-name
 	    ',(parse-callback-argspec argspec 'element-type)
 	    ,linear-index))
       ;; not setfable if it's a scalar
-      foreign-variable-name))
+      foreign-pointer-name))
 
 (defun array-element-refs (names argspecs dimension-values)
   "A list of forms reference each array element in succession.
-- 
GitLab