Small docstring fixes.

libguile/ChangeLog

@@ -1,5 +1,21 @@
 2002-03-15  Neil Jerram  <neil@ossau.uklinux.net>
 
+	* posix.c (scm_execl): Remove spurious whitespace from docstring.
+
+	* unif.c (scm_array_contents): Remove duplicate @deffnx line.
+
+	* struct.c (scm_struct_p, scm_struct_vtable_p): Align variable
+	name in docstring with C parameter name.
+
+	* sort.c (scm_merge), stacks.c (scm_make_stack): Take clearer
+	docstrings from unstable branch.
+
+	* print.c (scm_newline): Say what if port arg is omitted.
+
+	* objprop.c (scm_object_properties, scm_set_object_properties_x,
+	scm_object_property, scm_set_object_property_x): Remove incorrect
+	@deffnx lines from docstrings.
+
 	* debug.c (scm_debug_options): Change incorrect @var in docstring
 	to @code.
 

libguile/objprop.c

@@ -56,7 +56,6 @@
 
 SCM_DEFINE (scm_object_properties, "object-properties", 1, 0, 0, 
            (SCM obj),
-	    "@deffnx {Scheme Procedure} procedure-properties obj\n"
 	    "Return @var{obj}'s property list.")
 #define FUNC_NAME s_scm_object_properties
 {
@@ -67,7 +66,6 @@ SCM_DEFINE (scm_object_properties, "object-properties", 1, 0, 0,
 
 SCM_DEFINE (scm_set_object_properties_x, "set-object-properties!", 2, 0, 0,
 	    (SCM obj, SCM alist),
-	    "@deffnx {Scheme Procedure} set-procedure-properties! obj alist\n"
 	    "Set @var{obj}'s property list to @var{alist}.")
 #define FUNC_NAME s_scm_set_object_properties_x
 {
@@ -79,7 +77,6 @@ SCM_DEFINE (scm_set_object_properties_x, "set-object-properties!", 2, 0, 0,
 
 SCM_DEFINE (scm_object_property, "object-property", 2, 0, 0,
            (SCM obj, SCM key),
-	    "@deffnx {Scheme Procedure} procedure-property obj key\n"
 	    "Return the property of @var{obj} with name @var{key}.")
 #define FUNC_NAME s_scm_object_property
 {
@@ -91,7 +88,6 @@ SCM_DEFINE (scm_object_property, "object-property", 2, 0, 0,
 
 SCM_DEFINE (scm_set_object_property_x, "set-object-property!", 3, 0, 0,
 	    (SCM obj, SCM key, SCM value),
-	    "@deffnx {Scheme Procedure} set-procedure-property! obj key value\n"
 	    "In @var{obj}'s property list, set the property named @var{key}\n"
 	    "to @var{value}.")
 #define FUNC_NAME s_scm_set_object_property_x

libguile/posix.c

@@ -886,7 +886,7 @@ SCM_DEFINE (scm_execl, "execl", 1, 0, 1,
 	    "The remaining arguments are supplied to the process; from a C program\n"
 	    "they are accessible as the @code{argv} argument to @code{main}.\n"
 	    "Conventionally the first @var{arg} is the same as @var{path}.\n"
-	    "All arguments must be strings.  \n\n"
+	    "All arguments must be strings.\n\n"
 	    "If @var{arg} is missing, @var{path} is executed with a null\n"
 	    "argument list, which may have system-dependent side-effects.\n\n"
 	    "This procedure is currently implemented using the @code{execv} system\n"

libguile/print.c

@@ -1004,7 +1004,8 @@ SCM_DEFINE (scm_simple_format, "simple-format", 2, 0, 1,
 
 SCM_DEFINE (scm_newline, "newline", 0, 1, 0, 
             (SCM port),
-	    "Send a newline to @var{port}.")
+	    "Send a newline to @var{port}.\n"
+	    "If @var{port} is omitted, send to the current output port.")
 #define FUNC_NAME s_scm_newline
 {
   if (SCM_UNBNDP (port))

libguile/sort.c

@@ -516,9 +516,10 @@ 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),
-	    "Take 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"
+	    "Merge two already sorted lists into one.\n"
+	    "Given two lists @var{alist} and @var{blist}, such that\n"
+	    "@code{(sorted? alist less?)} and @code{(sorted? blist less?)},\n"
+	    "return 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.")

libguile/stacks.c

@@ -420,9 +420,26 @@ SCM_DEFINE (scm_make_stack, "make-stack", 1, 0, 1,
 	    "Create a new stack. If @var{obj} is @code{#t}, the current\n"
 	    "evaluation stack is used for creating the stack frames,\n"
 	    "otherwise the frames are taken from @var{obj} (which must be\n"
-	    "either a debug object or a continuation).\n"
-	    "@var{args} must be a list of integers and specifies how the\n"
-	    "resulting stack will be narrowed.")
+	    "either a debug object or a continuation).\n\n"
+	    "@var{args} should be a list containing any combination of\n"
+	    "integer, procedure and @code{#t} values.\n\n"
+	    "These values specify various ways of cutting away uninteresting\n"
+	    "stack frames from the top and bottom of the stack that\n"
+	    "@code{make-stack} returns.  They come in pairs like this:\n"
+	    "@code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}\n"
+	    "@var{outer_cut_2} @dots{})}.\n\n"
+	    "Each @var{inner_cut_N} can be @code{#t}, an integer, or a\n"
+	    "procedure.  @code{#t} means to cut away all frames up to but\n"
+	    "excluding the first user module frame.  An integer means to cut\n"
+	    "away exactly that number of frames.  A procedure means to cut\n"
+	    "away all frames up to but excluding the application frame whose\n"
+	    "procedure matches the specified one.\n\n"
+	    "Each @var{outer_cut_N} can be an integer or a procedure.  An\n"
+	    "integer means to cut away that number of frames.  A procedure\n"
+	    "means to cut away frames down to but excluding the application\n"
+	    "frame whose procedure matches the specified one.\n\n"
+	    "If the @var{outer_cut_N} of the last pair is missing, it is\n"
+	    "taken as 0.")
 #define FUNC_NAME s_scm_make_stack
 {
   long n, size;

libguile/struct.c

@@ -240,7 +240,7 @@ scm_struct_init (SCM handle, SCM layout, scm_t_bits * mem, int tail_elts, SCM in
 
 SCM_DEFINE (scm_struct_p, "struct?", 1, 0, 0, 
             (SCM x),
-	    "Return @code{#t} iff @var{obj} is a structure object, else\n"
+	    "Return @code{#t} iff @var{x} is a structure object, else\n"
 	    "@code{#f}.")
 #define FUNC_NAME s_scm_struct_p
 {
@@ -250,7 +250,7 @@ SCM_DEFINE (scm_struct_p, "struct?", 1, 0, 0,
 
 SCM_DEFINE (scm_struct_vtable_p, "struct-vtable?", 1, 0, 0, 
             (SCM x),
-	    "Return @code{#t} iff obj is a vtable structure.")
+	    "Return @code{#t} iff @var{x} is a vtable structure.")
 #define FUNC_NAME s_scm_struct_vtable_p
 {
   SCM layout;

libguile/unif.c

@@ -1371,7 +1371,6 @@ SCM_DEFINE (scm_array_set_x, "array-set!", 2, 0, 1,
 		     wouldn't have contiguous elements.  */
 SCM_DEFINE (scm_array_contents, "array-contents", 1, 1, 0,
            (SCM ra, SCM strict),
-	    "@deffnx {Scheme Procedure} array-contents array strict\n"
 	    "If @var{array} may be @dfn{unrolled} into a one dimensional shared array\n"
 	    "without changing their order (last subscript changing fastest), then\n"
 	    "@code{array-contents} returns that shared array, otherwise it returns\n"