Docstring patches.

[Martin Grabmueller]

Hello all,

I have added docstrings which were missing in the files struct.c,
weaks.c, srcprop.c and sort.c.  The patch is attached below.

I thought about adding docstrings to all the remaining files which
lacked them, but before I do all the necessary work I would like to
hear from you if this is generally wanted, and if yes, if I do it The
Right Way, or if the docstrings can be improved.

Regards,
  'martin

ChangeLog entry follows.

2001-01-29  Martin Grabmueller  <address@hidden>

        * struct.c (scm_make_vtable_vtable): Removed unnecessary "" from
        end of docstring.
        (scm_struct_set_x, scm_struct_vtable_tag, scm_struct_vtable_name,
        scm_set_struct_vtable_name_x): Added docstrings.

        * 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): Added docstrings.

        * 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.


===File ~/cvs/guile-core/libguile/doc-diff==================
Index: sort.c
===================================================================
RCS file: /cvs/guile/guile-core/libguile/sort.c,v
retrieving revision 1.27
diff -u -r1.27 sort.c
--- sort.c      2000/11/17 16:25:04     1.27
+++ sort.c      2001/01/29 20:30:57
@@ -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: srcprop.c
===================================================================
RCS file: /cvs/guile/guile-core/libguile/srcprop.c,v
retrieving revision 1.42
diff -u -r1.42 srcprop.c
--- srcprop.c   2001/01/25 11:09:21     1.42
+++ srcprop.c   2001/01/29 20:30:59
@@ -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: struct.c
===================================================================
RCS file: /cvs/guile/guile-core/libguile/struct.c,v
retrieving revision 1.67
diff -u -r1.67 struct.c
--- struct.c    2000/12/08 17:08:34     1.67
+++ struct.c    2001/01/29 20:31:02
@@ -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: weaks.c
===================================================================
RCS file: /cvs/guile/guile-core/libguile/weaks.c,v
retrieving revision 1.32
diff -u -r1.32 weaks.c
--- weaks.c     2000/12/29 22:18:06     1.32
+++ weaks.c     2001/01/29 20:31:04
@@ -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));
============================================================