Fixed documentation for make-guardian.

* module/ice-9/guardians.scm (make-guardian): Copy full documentation of
old C version.

module/ice-9/guardians.scm

@@ -89,7 +89,44 @@
 
 (define (make-guardian)
   "Create a new guardian.  A guardian protects a set of objects from
-garbage collection, allowing a program to apply cleanup or other"
+garbage collection, allowing a program to apply cleanup or other
+actions.
+
+@code{make-guardian} returns a procedure representing the guardian.
+Calling the guardian procedure with an argument adds the argument to
+the guardian's set of protected objects.  Calling the guardian
+procedure without an argument returns one of the protected objects
+which are ready for garbage collection, or @code{#f} if no such object
+is available.  Objects which are returned in this way are removed from
+the guardian.
+
+You can put a single object into a guardian more than once and you can
+put a single object into more than one guardian.  The object will then
+be returned multiple times by the guardian procedures.
+
+An object is eligible to be returned from a guardian when it is no
+longer referenced from outside any guardian.
+
+There is no guarantee about the order in which objects are returned
+from a guardian.  If you want to impose an order on finalization
+actions, for example, you can do that by keeping objects alive in some
+global data structure until they are no longer needed for finalizing
+other objects.
+
+Being an element in a weak vector, a key in a hash table with weak
+keys, or a value in a hash table with weak value does not prevent an
+object from being returned by a guardian.  But as long as an object
+can be returned from a guardian it will not be removed from such a
+weak vector or hash table.  In other words, a weak link does not
+prevent an object from being considered collectable, but being inside
+a guardian prevents a weak link from being broken.
+
+A key in a weak key hash table can be though of as having a strong
+reference to its associated value as long as the key is accessible.
+Consequently, when the key only accessible from within a guardian, the
+reference from the key to the value is also considered to be coming
+from within a guardian.  Thus, if there is no other reference to the
+value, it is eligible to be returned from a guardian."
   (define-values (push! pop!) (make-atomic-fifo))
   (define (guard! obj)
     (when (heap-object? obj)