summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDirk Herrmann <dirk@dirk-herrmanns-seiten.de>2001-01-30 14:53:20 +0000
committerDirk Herrmann <dirk@dirk-herrmanns-seiten.de>2001-01-30 14:53:20 +0000
commite32398681a4c31260ce85e087f17edb29962b14c (patch)
tree339cc3c1aba3be66c5d5d67e1468054cc8e12fa4
parent41ee56dde37d65598ec82de66fbd3c984292eafb (diff)
downloadguile-e32398681a4c31260ce85e087f17edb29962b14c.tar.gz
* Added docstrings by Martin Grabmueller.
-rw-r--r--libguile/ChangeLog16
-rw-r--r--libguile/sort.c54
-rw-r--r--libguile/srcprop.c11
-rw-r--r--libguile/struct.c13
-rw-r--r--libguile/weaks.c10
5 files changed, 79 insertions, 25 deletions
diff --git a/libguile/ChangeLog b/libguile/ChangeLog
index 8123b7241..3477aa69e 100644
--- a/libguile/ChangeLog
+++ b/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
diff --git a/libguile/sort.c b/libguile/sort.c
index e25f19cd9..8b7dd62da 100644
--- a/libguile/sort.c
+++ b/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;
@@ -909,8 +940,9 @@ 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),
-"")
+ (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;
diff --git a/libguile/srcprop.c b/libguile/srcprop.c
index f17125f91..341c9a670 100644
--- a/libguile/srcprop.c
+++ b/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;
diff --git a/libguile/struct.c b/libguile/struct.c
index 5c533f172..0746c0b9f 100644
--- a/libguile/struct.c
+++ b/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);
diff --git a/libguile/weaks.c b/libguile/weaks.c
index f0b006a5a..f340922fe 100644
--- a/libguile/weaks.c
+++ b/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));