guile/guile-core/libguile ChangeLog sort.c srcp...

[Dirk Herrmann]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Dirk Herrmann <address@hidden>  01/01/30 06:53:20

Modified files:
        guile-core/libguile: ChangeLog sort.c srcprop.c struct.c weaks.c 

Log message:
        * Added docstrings by Martin Grabmueller.

CVSWeb URLs:
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/libguile/ChangeLog.diff?r1=1.1254&r2=1.1255
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/libguile/sort.c.diff?r1=1.27&r2=1.28
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/libguile/srcprop.c.diff?r1=1.42&r2=1.43
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/libguile/struct.c.diff?r1=1.67&r2=1.68
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/libguile/weaks.c.diff?r1=1.32&r2=1.33

Patches:
Index: guile/guile-core/libguile/ChangeLog
diff -u guile/guile-core/libguile/ChangeLog:1.1254 
guile/guile-core/libguile/ChangeLog:1.1255
--- guile/guile-core/libguile/ChangeLog:1.1254  Mon Jan 29 10:23:34 2001
+++ guile/guile-core/libguile/ChangeLog Tue Jan 30 06:53:20 2001
@@ -1,3 +1,19 @@
+2001-01-29  Martin Grabmueller  <address@hidden>
+
+       * 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  <address@hidden>
 
        * eval.c (SCM_APPLY): Check that primitives which take 1 arg
Index: guile/guile-core/libguile/sort.c
diff -u guile/guile-core/libguile/sort.c:1.27 
guile/guile-core/libguile/sort.c:1.28
--- guile/guile-core/libguile/sort.c:1.27       Fri Nov 17 08:25:04 2000
+++ guile/guile-core/libguile/sort.c    Tue Jan 30 06:53:20 2001
@@ -418,7 +418,10 @@
 
 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 @@
  * (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 @@
    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_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_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, "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_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, "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 @@
 /* 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;
@@ -909,8 +940,9 @@
 
 /* stable */
 SCM_DEFINE (scm_sort_list, "sort-list", 2, 0, 0, 
-  (SCM items, SCM less),
-"")
+           (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;
Index: guile/guile-core/libguile/srcprop.c
diff -u guile/guile-core/libguile/srcprop.c:1.42 
guile/guile-core/libguile/srcprop.c:1.43
--- guile/guile-core/libguile/srcprop.c:1.42    Thu Jan 25 03:09:21 2001
+++ guile/guile-core/libguile/srcprop.c Tue Jan 30 06:53:20 2001
@@ -167,7 +167,7 @@
 
 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 @@
    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_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_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;
Index: guile/guile-core/libguile/struct.c
diff -u guile/guile-core/libguile/struct.c:1.67 
guile/guile-core/libguile/struct.c:1.68
--- guile/guile-core/libguile/struct.c:1.67     Fri Dec  8 09:08:34 2000
+++ guile/guile-core/libguile/struct.c  Tue Jan 30 06:53:20 2001
@@ -513,8 +513,7 @@
            "(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_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_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_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_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);
Index: guile/guile-core/libguile/weaks.c
diff -u guile/guile-core/libguile/weaks.c:1.32 
guile/guile-core/libguile/weaks.c:1.33
--- guile/guile-core/libguile/weaks.c:1.32      Fri Dec 29 14:18:06 2000
+++ guile/guile-core/libguile/weaks.c   Tue Jan 30 06:53:20 2001
@@ -144,7 +144,8 @@
 
 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_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_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_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));