* Added docstrings by Martin Grabmueller.

libguile/ChangeLog

@@ -1,3 +1,19 @@
+2001-01-29  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
+
+	* struct.c (scm_make_vtable_vtable): Removed unnecessary "" from
+	end of docstring.
+
+	* struct.c (scm_struct_set_x, scm_struct_vtable_tag,
+	scm_struct_vtable_name, scm_set_struct_vtable_name_x), weaks.c
+	(scm_make_weak_value_hash_table, scm_make_doubly_weak_hash_table,
+	scm_weak_value_hash_table_p, scm_doubly_weak_hash_table_p),
+	srcprop.c (scm_source_properties, scm_set_source_properties_x,
+	scm_source_property, scm_set_source_property_x), sort.c
+	(scm_sort_list_x, scm_restricted_vector_sort_x, scm_sorted_p,
+	scm_merge, scm_merge_x, scm_sort_x, scm_sort, scm_stable_sort_x,
+	scm_stable_sort, scm_sort_list_x, scm_sort_list): Added
+	docstrings.
+
 2001-01-29  Mikael Djurfeldt  <mdj@linnaeus.mit.edu>
 
 	* eval.c (SCM_APPLY): Check that primitives which take 1 arg

libguile/sort.c

@@ -418,7 +418,10 @@ scm_cmp_function (SCM p)
 
 SCM_DEFINE (scm_restricted_vector_sort_x, "restricted-vector-sort!", 4, 0, 0, 
             (SCM vec, SCM less, SCM startpos, SCM endpos),
-"")
+	    "Sort the vector @var{vec}, using @var{less} for comparing\n"
+	    "the vector elements.  @var{startpos} and @var{endpos} delimit\n"
+	    "the range of the vector which gets sorted.  The return value\n"
+	    "is not specified.")
 #define FUNC_NAME s_scm_restricted_vector_sort_x
 {
   size_t  vlen, spos, len, size = sizeof (SCM);
@@ -447,7 +450,9 @@ SCM_DEFINE (scm_restricted_vector_sort_x, "restricted-vector-sort!", 4, 0, 0,
  * (not (less? (list-ref list i) (list-ref list (- i 1)))). */
 SCM_DEFINE (scm_sorted_p, "sorted?", 2, 0, 0,
             (SCM items, SCM less),
-"")
+	    "Return @code{#t} iff @var{items} is a list or a vector such that\n"
+	    "for all 1 <= i <= m, the predicate @var{less} returns true when\n"
+	    "applied to all elements i - 1 and i")
 #define FUNC_NAME s_scm_sorted_p
 {
   long len, j;			/* list/vector length, temp j */
@@ -514,7 +519,12 @@ SCM_DEFINE (scm_sorted_p, "sorted?", 2, 0, 0,
    Note:  this does _not_ accept vectors. */
 SCM_DEFINE (scm_merge, "merge", 3, 0, 0, 
             (SCM alist, SCM blist, SCM less),
-"")
+	    "Takes two lists @var{alist} and @var{blist} such that\n"
+	    "@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and\n"
+	    "returns a new list in which the elements of @var{alist} and\n"
+	    "@var{blist} have been stably interleaved so that\n"
+	    "@code{(sorted? (merge alist blist less?) less?)}.\n"
+	    "Note:  this does _not_ accept vectors.")
 #define FUNC_NAME s_scm_merge
 {
   long alen, blen;		/* list lengths */
@@ -621,7 +631,13 @@ scm_merge_list_x (SCM alist, SCM blist,
 
 SCM_DEFINE (scm_merge_x, "merge!", 3, 0, 0, 
             (SCM alist, SCM blist, SCM less),
-"")
+	    "Takes two lists @var{alist} and @var{blist} such that\n"
+	    "@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and\n"
+	    "returns a new list in which the elements of @var{alist} and\n"
+	    "@var{blist} have been stably interleaved so that\n"
+	    " @code{(sorted? (merge alist blist less?) less?)}.\n"
+	    "This is the destructive variant of @code{merge}\n"
+	    "Note:  this does _not_ accept vectors.")
 #define FUNC_NAME s_scm_merge_x
 {
   long alen, blen;		/* list lengths */
@@ -693,7 +709,11 @@ scm_merge_list_step (SCM * seq,
 /* scm_sort_x manages lists and vectors, not stable sort */
 SCM_DEFINE (scm_sort_x, "sort!", 2, 0, 0, 
             (SCM items, SCM less),
-"")
+	    "Sort the sequence @var{items}, which may be a list or a\n"
+	    "vector.  @var{less} is used for comparing the sequence\n"
+	    "elements.  The sorting is destructive, that means that the\n"
+	    "input sequence is modified to produce the sorted result.\n"
+	    "This is not a stable sort.")
 #define FUNC_NAME s_scm_sort_x
 {
   long len;			/* list/vector length */
@@ -725,7 +745,9 @@ SCM_DEFINE (scm_sort_x, "sort!", 2, 0, 0,
 
 SCM_DEFINE (scm_sort, "sort", 2, 0, 0, 
             (SCM items, SCM less),
-"")
+	    "Sort the sequence @var{items}, which may be a list or a\n"
+	    "vector.  @var{less} is used for comparing the sequence\n"
+	    "elements.  This is not a stable sort.")
 #define FUNC_NAME s_scm_sort
 {
   SCM sortvec;			/* the vector we actually sort */
@@ -816,7 +838,11 @@ scm_merge_vector_step (void *const vp,
 
 SCM_DEFINE (scm_stable_sort_x, "stable-sort!", 2, 0, 0, 
             (SCM items, SCM less),
-"")
+	    "Sort the sequence @var{items}, which may be a list or a\n"
+	    "vector. @var{less} is used for comparing the sequence elements.\n"
+	    "The sorting is destructive, that means that the input sequence\n"
+	    "is modified to produce the sorted result.\n"
+	    "This is a stable sort.")
 #define FUNC_NAME s_scm_stable_sort_x
 {
   long len;			/* list/vector length */
@@ -854,7 +880,9 @@ SCM_DEFINE (scm_stable_sort_x, "stable-sort!", 2, 0, 0,
 
 SCM_DEFINE (scm_stable_sort, "stable-sort", 2, 0, 0, 
             (SCM items, SCM less),
-"")
+	    "Sort the sequence @var{items}, which may be a list or a\n"
+	    "vector. @var{less} is used for comparing the sequence elements.\n"
+	    "This is a stable sort.")
 #define FUNC_NAME s_scm_stable_sort
 {
   long len;			/* list/vector length */
@@ -897,7 +925,10 @@ SCM_DEFINE (scm_stable_sort, "stable-sort", 2, 0, 0,
 /* stable */
 SCM_DEFINE (scm_sort_list_x, "sort-list!", 2, 0, 0, 
             (SCM items, SCM less),
-"")
+	    "Sort the list @var{items}, using @var{less} for comparing the\n"
+	    "list elements. The sorting is destructive, that means that the\n"
+	    "input list is modified to produce the sorted result.\n"
+	    "This is a stable sort.")
 #define FUNC_NAME s_scm_sort_list_x
 {
   long len;
@@ -910,7 +941,8 @@ SCM_DEFINE (scm_sort_list_x, "sort-list!", 2, 0, 0,
 /* stable */
 SCM_DEFINE (scm_sort_list, "sort-list", 2, 0, 0, 
 	    (SCM items, SCM less),
-"")
+	    "Sort the list @var{items}, using @var{less} for comparing the\n"
+	    "list elements. This is a stable sort.")
 #define FUNC_NAME s_scm_sort_list
 {
   long len;

libguile/srcprop.c

@@ -167,7 +167,7 @@ scm_srcprops_to_plist (SCM obj)
 
 SCM_DEFINE (scm_source_properties, "source-properties", 1, 0, 0, 
             (SCM obj),
-"")
+	    "Return the source property association list of @var{obj}.")
 #define FUNC_NAME s_scm_source_properties
 {
   SCM p;
@@ -189,7 +189,8 @@ SCM_DEFINE (scm_source_properties, "source-properties", 1, 0, 0,
    and try to make a srcprops-object...? */
 SCM_DEFINE (scm_set_source_properties_x, "set-source-properties!", 2, 0, 0,
             (SCM obj, SCM plist),
-"")
+	    "Install the association list @var{plist} as the source property\n"
+	    "list for @var{obj}.")
 #define FUNC_NAME s_scm_set_source_properties_x
 {
   SCM handle;
@@ -208,7 +209,8 @@ SCM_DEFINE (scm_set_source_properties_x, "set-source-properties!", 2, 0, 0,
 
 SCM_DEFINE (scm_source_property, "source-property", 2, 0, 0,
             (SCM obj, SCM key),
-"")
+	    "Return the source property specified by @var{key} from\n"
+	    "@var{obj}'s source property list.")
 #define FUNC_NAME s_scm_source_property
 {
   SCM p;
@@ -240,7 +242,8 @@ SCM_DEFINE (scm_source_property, "source-property", 2, 0, 0,
 
 SCM_DEFINE (scm_set_source_property_x, "set-source-property!", 3, 0, 0,
             (SCM obj, SCM key, SCM datum),
-"")
+	    "Set the source property of object @var{obj}, which is specified by\n"
+	    "@var{key} to @var{datum}.  Normally, the key will be a symbol.")
 #define FUNC_NAME s_scm_set_source_property_x
 {
   scm_whash_handle h;

libguile/struct.c

@@ -513,8 +513,7 @@ SCM_DEFINE (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
 	    "(define (make-ball type owner) (make-struct type 0 owner))\n\n"
 	    "(define ball (make-ball green 'Nisse))\n"
 	    "ball @result{} #<a green ball owned by Nisse>\n"
-	    "@end example\n"
+	    "@end example\n")
-	    "")
 #define FUNC_NAME s_scm_make_vtable_vtable
 {
   SCM fields;
@@ -637,7 +636,9 @@ SCM_DEFINE (scm_struct_ref, "struct-ref", 2, 0, 0,
 
 SCM_DEFINE (scm_struct_set_x, "struct-set!", 3, 0, 0,
             (SCM handle, SCM pos, SCM val),
-	    "")
+	    "Set the slot of the structure @var{handle} with index @var{pos}\n"
+	    "to @var{val}.  Signal an error if the slot can not be written\n"
+	    "to.")
 #define FUNC_NAME s_scm_struct_set_x
 {
   scm_bits_t * data;
@@ -722,7 +723,7 @@ SCM_DEFINE (scm_struct_vtable, "struct-vtable", 1, 0, 0,
 
 SCM_DEFINE (scm_struct_vtable_tag, "struct-vtable-tag", 1, 0, 0, 
             (SCM handle),
-	    "")
+	    "Return the vtable tag of the structure @var{handle}.")
 #define FUNC_NAME s_scm_struct_vtable_tag
 {
   SCM_VALIDATE_VTABLE (1,handle);
@@ -761,7 +762,7 @@ scm_struct_create_handle (SCM obj)
 
 SCM_DEFINE (scm_struct_vtable_name, "struct-vtable-name", 1, 0, 0, 
             (SCM vtable),
-	    "")
+	    "Return the name of the vtable @var{vtable}.")
 #define FUNC_NAME s_scm_struct_vtable_name
 {
   SCM_VALIDATE_VTABLE (1,vtable);
@@ -771,7 +772,7 @@ SCM_DEFINE (scm_struct_vtable_name, "struct-vtable-name", 1, 0, 0,
 
 SCM_DEFINE (scm_set_struct_vtable_name_x, "set-struct-vtable-name!", 2, 0, 0, 
             (SCM vtable, SCM name),
-	    "")
+	    "Set the name of the vtable @var{vtable} to @var{name}.")
 #define FUNC_NAME s_scm_set_struct_vtable_name_x
 {
   SCM_VALIDATE_VTABLE (1,vtable);

libguile/weaks.c

@@ -144,7 +144,8 @@ SCM_DEFINE (scm_make_weak_key_hash_table, "make-weak-key-hash-table", 1, 0, 0,
 
 SCM_DEFINE (scm_make_weak_value_hash_table, "make-weak-value-hash-table", 1, 0, 0, 
             (SCM k),
-	    "")
+	    "Return a hash table with weak values with @var{size} buckets.\n"
+	    "(@pxref{Hash Tables})")
 #define FUNC_NAME s_scm_make_weak_value_hash_table
 {
   SCM v;
@@ -161,7 +162,8 @@ SCM_DEFINE (scm_make_weak_value_hash_table, "make-weak-value-hash-table", 1, 0,
 
 SCM_DEFINE (scm_make_doubly_weak_hash_table, "make-doubly-weak-hash-table", 1, 0, 0, 
             (SCM k),
-	    "")
+	    "Return a hash table with weak keys and values with @var{size}\n"
+	    "buckets.  (@pxref{Hash Tables})")
 #define FUNC_NAME s_scm_make_doubly_weak_hash_table
 {
   SCM v;
@@ -190,7 +192,7 @@ SCM_DEFINE (scm_weak_key_hash_table_p, "weak-key-hash-table?", 1, 0, 0,
 
 SCM_DEFINE (scm_weak_value_hash_table_p, "weak-value-hash-table?", 1, 0, 0, 
             (SCM x),
-	    "")
+	    "Return @var{#t} if @var{x} is a weak value hash table.")
 #define FUNC_NAME s_scm_weak_value_hash_table_p
 {
   return SCM_BOOL(SCM_WVECTP (x) && SCM_IS_WHVEC_V(x));
@@ -200,7 +202,7 @@ SCM_DEFINE (scm_weak_value_hash_table_p, "weak-value-hash-table?", 1, 0, 0,
 
 SCM_DEFINE (scm_doubly_weak_hash_table_p, "doubly-weak-hash-table?", 1, 0, 0, 
             (SCM x),
-	    "")
+	    "Return @var{#t} if @var{x} is a doubly weak hash table.")
 #define FUNC_NAME s_scm_doubly_weak_hash_table_p
 {
   return SCM_BOOL(SCM_WVECTP (x) && SCM_IS_WHVEC_B (x));