[doc][misc] pythonize, rename parameter of pyvalue, indentation

Author: digikar99

src/python-process.lisp

@@ -501,9 +501,9 @@ Use PYVALUE* if you want to refer to names containing full-stops."
                       (string slot-name)
                       (symbol (pythonize-symbol slot-name))))
          (return-value (pyforeign-funcall "PyObject_GetAttrString"
-                                            :pointer object-pointer
-                                            :string slot-name
-                                            :pointer)))
+                                          :pointer object-pointer
+                                          :string slot-name
+                                          :pointer)))
     (ensure-non-null-pointer return-value
                              :format-control
                              "~A~%in python does not have the attribute ~A"
@@ -561,7 +561,7 @@ Use PYVALUE* if you want to refer to names containing full-stops."
         (when previous-value
           (setf (%pyslot-value previous-value previous-name) new-value)))))
 
-(defun pyvalue (python-value-or-variable)
+(defun pyvalue (python-name-or-variable)
   "Get the value of a python-name-or-variable.
 Example:
 
@@ -573,13 +573,13 @@ Example:
     \"/home/user/miniconda3/lib/python3.10/lib-dynload\"
     \"/home/user/miniconda3/lib/python3.10/site-packages\")
 "
-  (declare (type (or python-object string) python-value-or-variable))
+  (declare (type (or python-object string) python-name-or-variable))
   (python-start-if-not-alive)
   (if *in-with-remote-objects-p*
-      (pyvalue* python-value-or-variable)
-      (with-pygc (lispify (pyvalue* python-value-or-variable)))))
+      (pyvalue* python-name-or-variable)
+      (with-pygc (lispify (pyvalue* python-name-or-variable)))))
 
-(defun (setf pyvalue) (new-value python-value-or-variable)
+(defun (setf pyvalue) (new-value python-name-or-variable)
   "Set the value of a python-name-or-variable.
 Example:
 
@@ -596,10 +596,10 @@ Example:
     \"/home/user/miniconda3/lib/python3.10/lib-dynload\"
     \"/home/user/miniconda3/lib/python3.10/site-packages\")
 "
-  (declare (type string python-value-or-variable))
+  (declare (type string python-name-or-variable))
   (python-start-if-not-alive)
   (with-pygc
-    (setf (pyvalue* python-value-or-variable)
+    (setf (pyvalue* python-name-or-variable)
           ;; UNTRACK because we do not want to lose reference to this object!
           (pyuntrack (%pythonize new-value)))
     new-value))

src/pythonizers.lisp

@@ -100,7 +100,16 @@ the same lisp objects which are EQ to each other. Returns NIL in all other cases
            `(pyeval ,(pycall "repr" pointer))))))
 
 (declaim (type (function (t) foreign-pointer) pythonize))
-(defgeneric pythonize (lisp-value-or-object))
+(defgeneric pythonize (lisp-value-or-object)
+  (:documentation "Given a lisp object, return a CFFI:FOREIGN-POINTER pointing to the python object corresponding to the given lisp object.
+
+The implemented methods are expected to return a new (strong) reference
+to the python object. The method is also expected to call PYTRACK
+to notify the PYGC functionality to delete the reference once the object
+is no longer needed.
+
+See the documentation for PYGC to understand when reference deletion
+takes place."))
 
 (defmethod pythonize (lisp-object)
   (pycall* "_py4cl_UnknownLispObject" (object-handle lisp-object)))