* sort.c: typo in comment fixed.

* keywords.c: Added documentation.

* guardians.c: Added documentation (could be better).

* gc.c: Added docs for gc-set-debug-check-freelist.

* eq.c: Added docs for eq?, eqv? equal? abridged from R4RS.

* boolean.c: Added docs for `not', `boolean?' (by hand).

libguile/boolean.c

@@ -53,8 +53,8 @@
 
 
 SCM_DEFINE (scm_not, "not", 1, 0, 0, 
-           (SCM x),
-"")
+            (SCM x),
+            "Return #t iff X is #f, else return #f.\n")
 #define FUNC_NAME s_scm_not
 {
   return SCM_BOOL(SCM_FALSEP(x));
@@ -64,7 +64,7 @@ SCM_DEFINE (scm_not, "not", 1, 0, 0,
 
 SCM_DEFINE (scm_boolean_p, "boolean?", 1, 0, 0, 
            (SCM obj),
-"")
+            "Return #t iff OBJ is either #t or #f.\n")
 #define FUNC_NAME s_scm_boolean_p
 {
   return SCM_BOOL(SCM_BOOL_F == obj || SCM_BOOL_T == obj);

libguile/eq.c

@@ -56,7 +56,11 @@
 
 SCM_DEFINE1 (scm_eq_p, "eq?", scm_tc7_rpsubr,
              (SCM x, SCM y),
-"")
+             "Return #t iff X references the same object as Y.\n"
+             "`eq?' is similar to `eqv?' except that in some cases\n"
+             "it is capable of discerning distinctions finer than\n"
+             "those detectable by `eqv?'.\n"
+             "")
 #define FUNC_NAME s_scm_eq_p
 {
   return SCM_BOOL(x==y);
@@ -66,7 +70,11 @@ SCM_DEFINE1 (scm_eq_p, "eq?", scm_tc7_rpsubr,
 
 SCM_DEFINE1 (scm_eqv_p, "eqv?", scm_tc7_rpsubr,
              (SCM x, SCM y),
-"")
+             "The `eqv?' procedure defines a useful equivalence relation on objects.\n"
+             "Briefly, it returns #t if X and Y should normally be\n"
+             "regarded as the same object.  This relation is left\n"
+             "slightly open to interpretation, but works for comparing\n"
+             "immediate integers, characters, and inexact numbers.\n")
 #define FUNC_NAME s_scm_eqv_p
 {
   if (x==y) return SCM_BOOL_T;
@@ -91,7 +99,13 @@ SCM_DEFINE1 (scm_eqv_p, "eqv?", scm_tc7_rpsubr,
 
 SCM_DEFINE1 (scm_equal_p, "equal?", scm_tc7_rpsubr,
              (SCM x, SCM y),
-"")
+             "Return #t iff X and Y are recursively `eqv?' equivalent.\n"
+             "`equal?' recursively compares the contents of pairs, vectors, and\n"
+             "strings, applying `eqv?' on other objects such as numbers and\n"
+             "symbols.  A rule of thumb is that objects are generally `equal?'\n"
+             "if they print the same.  `Equal?' may fail to terminate if its\n"
+             "arguments are circular data structures.\n"
+             "")
 #define FUNC_NAME s_scm_equal_p
 {
   SCM_CHECK_STACK;

libguile/gc.c

@@ -300,7 +300,9 @@ static int scm_debug_check_freelist = 0;
 
 SCM_DEFINE (scm_gc_set_debug_check_freelist_x, "gc-set-debug-check-freelist!", 1, 0, 0, 
             (SCM flag),
-"")
+            "If FLAG is #t, check the freelist for consistency on each cell allocation.\n"
+            "This procedure only exists because the GUILE_DEBUG_FREELIST \n"
+            "compile-time flag was selected.\n")
 #define FUNC_NAME s_scm_gc_set_debug_check_freelist_x
 {
   SCM_VALIDATE_BOOL_COPY (1,flag,scm_debug_check_freelist);

libguile/guardians.c

@@ -151,7 +151,16 @@ static SCM guard1;
 
 SCM_DEFINE (scm_make_guardian, "make-guardian", 0, 0, 0, 
             (),
-"")
+            "Return a new guardian object.\n"
+            "A guardian allows dynamically allocated objects to be\n"
+            "saved from deallocation by the garbage collector so that\n"
+            "clean up or other actions can be performed using the data\n"
+            "stored within the objects.\n"
+            "See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)\n"
+            "\"Guardians in a Generation-Based Garbage Collector\".\n"
+            "ACM SIGPLAN Conference on Programming Language Design\n"
+            "and Implementation, June 1993\n"
+            "")
 #define FUNC_NAME s_scm_make_guardian
 {
   SCM cclo = scm_makcclo (guard1, 2L);

libguile/keywords.c

@@ -70,7 +70,7 @@ int scm_tc16_kw;
 
 SCM_DEFINE (scm_make_keyword_from_dash_symbol, "make-keyword-from-dash-symbol", 1, 0, 0, 
             (SCM symbol),
-"")
+            "Return a keyword object from SYMBOL that starts with `-' (a dash).")
 #define FUNC_NAME s_scm_make_keyword_from_dash_symbol
 {
   SCM vcell;
@@ -107,9 +107,8 @@ scm_c_make_keyword (char *s)
 }
 
 SCM_DEFINE (scm_keyword_p, "keyword?", 1, 0, 0, 
-           (SCM obj),
-	    "@code{keyword?} returns @code{#t} if the argument @var{kw} is a keyword;\n"
-	    "it returns @code{#f} otherwise.")
+            (SCM obj),
+	    "Returns #t if the argument OBJ is a keyword, else #f.")
 #define FUNC_NAME s_scm_keyword_p
 {
   return SCM_BOOL(SCM_KEYWORDP (obj));
@@ -118,9 +117,9 @@ SCM_DEFINE (scm_keyword_p, "keyword?", 1, 0, 0,
 
 
 SCM_DEFINE (scm_keyword_dash_symbol, "keyword-dash-symbol", 1, 0, 0, 
-           (SCM keyword),
-	    "@code{keyword-dash-symbol} [FIXME: have no idea what this does; it is\n"
-	    "not commented.]")
+            (SCM keyword),
+	    "Return KEYWORD as a dash symbol.\n"
+            "This is the inverse of `make-keyword-from-dash-symbol'.\n")
 #define FUNC_NAME s_scm_keyword_dash_symbol
 {
   SCM_VALIDATE_KEYWORD (1,keyword);

libguile/sort.c

@@ -413,7 +413,7 @@ scm_cmp_function (SCM p)
 /* Question: Is there any need to make this a more general array sort?
    It is probably enough to manage the vector type. */
 /* endpos equal as for substring, i.e. endpos is not included. */
-/* More natural wih length? */
+/* More natural with length? */
 
 SCM_DEFINE (scm_restricted_vector_sort_x, "restricted-vector-sort!", 4, 0, 0, 
             (SCM vec, SCM less, SCM startpos, SCM endpos),