Added some docstrings and changed exports

[cl-gtk2.git] / glib / gobject.foreign.lisp

diff --git a/glib/gobject.foreign.lisp b/glib/gobject.foreign.lisp
index 0738cdc..051d700 100644 (file)
--- a/glib/gobject.foreign.lisp
+++ b/glib/gobject.foreign.lisp
@@ -1,10 +1,16 @@
 (in-package :gobject)
 
-(defgeneric release (object))
+(defgeneric release (object)
+  (:documentation "Manually frees the Lisp reference to the @code{object}. Probably should not be called.
+
+@arg[object]{an instance of @class{g-object}}"))
 
 (defmethod release ((object null)))
 
 (defun release* (&rest objects)
+  "Calls @fun{release} on all objects in @code{objects}
+
+@arg[objects]{a list of instances of @class{g-object}}"
   (declare (dynamic-extent objects))
   (loop
      for object in objects
@@ -31,14 +37,19 @@
 (defvar *registered-stable-pointers* (make-array 0 :adjustable t :fill-pointer t))
 
 (defun allocate-stable-pointer (thing)
+  "Allocates the stable pointer for @code{thing}. Stable pointer is an integer that can be dereferenced with @fun{get-stable-pointer-value} and freed with @fun{free-stable-pointer}. Stable pointers are used to pass references to lisp objects to foreign code.
+@arg[thing]{any object}
+@return{integer}"
   (let ((id (find-fresh-id)))
     (setf (aref *registered-stable-pointers* id) thing)
     (make-pointer id)))
 
 (defun free-stable-pointer (stable-pointer)
+  "Frees the stable pointer previously allocated by @fun{allocate-stable-pointer}"
   (setf (aref *registered-stable-pointers* (pointer-address stable-pointer)) nil))
 
 (defun get-stable-pointer-value (stable-pointer)
+  "Returns the objects that is referenced by stable pointer previously allocated by @fun{allocate-stable-pointer}. May be called any number of times."
   (when (<= 0 (pointer-address stable-pointer) (length *registered-stable-pointers*))
     (aref *registered-stable-pointers* (pointer-address stable-pointer))))
 
@@ -48,6 +59,10 @@
              (1- (length *registered-stable-pointers*)))))
 
 (defmacro with-stable-pointer ((ptr expr) &body body)
+  "Executes @code{body} with @code{ptr} bound to the stable pointer to result of evaluating @code{expr}.
+
+@arg[ptr]{a symbol naming the variable which will hold the stable pointer value}
+@arg[expr]{an expression}"
   `(let ((,ptr (allocate-stable-pointer ,expr)))
      (unwind-protect
           (progn ,@body)