This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Re: Coordinating docstring work
I have filled in the missing docstrings for the following files:
alist.c, list.c, and boolean.c. All text was taken verbatim from
either scheme.texi or r4rs.texi except for the text for list* (in
list.c) which was pulled from cl.texi from Emacs and the text for
delq1! which was is a slight rewording of the the existing delq! text.
Ryan
Index: alist.c
===================================================================
RCS file: /cvs/guile/guile/guile-core/libguile/alist.c,v
retrieving revision 1.11
diff -c -r1.11 alist.c
*** alist.c 1999/12/16 20:48:03 1.11
--- alist.c 1999/12/18 18:48:07
***************
*** 160,166 ****
GUILE_PROC(scm_assv, "assv", 2, 0, 0,
(SCM x, SCM alist),
! "")
#define FUNC_NAME s_scm_assv
{
SCM tmp;
--- 160,166 ----
GUILE_PROC(scm_assv, "assv", 2, 0, 0,
(SCM x, SCM alist),
! "See @code{assq}.")
#define FUNC_NAME s_scm_assv
{
SCM tmp;
Index: list.c
===================================================================
RCS file: /cvs/guile/guile/guile-core/libguile/list.c,v
retrieving revision 1.18
diff -c -r1.18 list.c
*** list.c 1999/12/16 20:48:04 1.18
--- list.c 1999/12/18 18:50:01
***************
*** 91,97 ****
GUILE_PROC(scm_list, "list", 0, 0, 1,
(SCM objs),
! "")
#define FUNC_NAME s_scm_list
{
return objs;
--- 91,97 ----
GUILE_PROC(scm_list, "list", 0, 0, 1,
(SCM objs),
! "Returns a newly allocated list of its arguments.")
#define FUNC_NAME s_scm_list
{
return objs;
***************
*** 101,107 ****
GUILE_PROC (scm_list_star, "list*", 1, 0, 1,
(SCM arg, SCM rest),
! "")
#define FUNC_NAME s_scm_list_star
{
if (SCM_NIMP (rest))
--- 101,111 ----
GUILE_PROC (scm_list_star, "list*", 1, 0, 1,
(SCM arg, SCM rest),
! "This function constructs a list of its arguments. The final argument
! becomes the @code{cdr} of the last cell constructed. Thus,
! @code{(list* @var{a} @var{b} @var{c})} is equivalent to @code{(cons
! @var{a} (cons @var{b} @var{c}))}, and @code{(list* @var{a} @var{b}
! nil)} is equivalent to @code{(list @var{a} @var{b})}.")
#define FUNC_NAME s_scm_list_star
{
if (SCM_NIMP (rest))
***************
*** 124,130 ****
GUILE_PROC(scm_null_p, "null?", 1, 0, 0,
(SCM x),
! "")
#define FUNC_NAME s_scm_null_p
{
return SCM_BOOL(SCM_NULLP(x));
--- 128,136 ----
GUILE_PROC(scm_null_p, "null?", 1, 0, 0,
(SCM x),
! "Returns @t{#t} if @var{obj} is the empty list,
! @cindex @w{empty list}
! otherwise returns @t{#f}.")
#define FUNC_NAME s_scm_null_p
{
return SCM_BOOL(SCM_NULLP(x));
***************
*** 133,139 ****
GUILE_PROC(scm_list_p, "list?", 1, 0, 0,
(SCM x),
! "")
#define FUNC_NAME s_scm_list_p
{
return SCM_BOOL(scm_ilength(x)>=0);
--- 139,147 ----
GUILE_PROC(scm_list_p, "list?", 1, 0, 0,
(SCM x),
! "Returns @t{#t} if @var{obj} is a list, otherwise returns @t{#f}.
! By definition, all lists have finite length and are terminated by
! the empty list.")
#define FUNC_NAME s_scm_list_p
{
return SCM_BOOL(scm_ilength(x)>=0);
***************
*** 173,179 ****
GUILE_PROC(scm_length, "length", 1, 0, 0,
(SCM lst),
! "")
#define FUNC_NAME s_scm_length
{
int i;
--- 181,187 ----
GUILE_PROC(scm_length, "length", 1, 0, 0,
(SCM lst),
! "Returns the length of @var{list}.")
#define FUNC_NAME s_scm_length
{
int i;
***************
*** 188,197 ****
GUILE_PROC (scm_append, "append", 0, 0, 1,
(SCM args),
! "A destructive version of @code{append} (@pxref{Pairs and Lists,,,r4rs,
! The Revised^4 Report on Scheme}). The cdr field of each list's final
! pair is changed to point to the head of the next list, so no consing is
! performed. Return a pointer to the mutated list.")
#define FUNC_NAME s_scm_append
{
SCM res = SCM_EOL;
--- 196,203 ----
GUILE_PROC (scm_append, "append", 0, 0, 1,
(SCM args),
! "Returns a list consisting of the elements of the first @var{list}
! followed by the elements of the other @var{list}s.")
#define FUNC_NAME s_scm_append
{
SCM res = SCM_EOL;
***************
*** 223,229 ****
GUILE_PROC (scm_append_x, "append!", 0, 0, 1,
(SCM args),
! "")
#define FUNC_NAME s_scm_append_x
{
SCM arg;
--- 229,238 ----
GUILE_PROC (scm_append_x, "append!", 0, 0, 1,
(SCM args),
! "A destructive version of @code{append} (@pxref{Pairs and Lists,,,r4rs,
! The Revised^4 Report on Scheme}). The cdr field of each list's final
! pair is changed to point to the head of the next list, so no consing is
! performed. Return a pointer to the mutated list.")
#define FUNC_NAME s_scm_append_x
{
SCM arg;
***************
*** 308,314 ****
GUILE_PROC (scm_reverse_x, "reverse!", 1, 1, 0,
(SCM ls, SCM new_tail),
! "")
#define FUNC_NAME s_scm_reverse_x
{
SCM old_tail;
--- 317,333 ----
GUILE_PROC (scm_reverse_x, "reverse!", 1, 1, 0,
(SCM ls, SCM new_tail),
! "A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r4rs,
! The Revised^4 Report on Scheme}). The cdr of each cell in @var{lst} is
! modified to point to the previous list element. Return a pointer to the
! head of the reversed list.
!
! Caveat: because the list is modified in place, the tail of the original
! list now becomes its head, and the head of the original list now becomes
! the tail. Therefore, the @var{lst} symbol to which the head of the
! original list was bound now points to the tail. To ensure that the head
! of the modified list is not lost, it is wise to save the return value of
! @code{reverse!}")
#define FUNC_NAME s_scm_reverse_x
{
SCM old_tail;
***************
*** 335,341 ****
GUILE_PROC(scm_list_ref, "list-ref", 2, 0, 0,
(SCM lst, SCM k),
! "")
#define FUNC_NAME s_scm_list_ref
{
register long i;
--- 354,361 ----
GUILE_PROC(scm_list_ref, "list-ref", 2, 0, 0,
(SCM lst, SCM k),
! "Returns the @var{k}th element of @var{list}. (This is the same
! as the car of @code{(list-tail @var{list} @var{k})}.)")
#define FUNC_NAME s_scm_list_ref
{
register long i;
***************
*** 492,498 ****
GUILE_PROC (scm_sloppy_memv, "sloppy-memv", 2, 0, 0,
(SCM x, SCM lst),
! "")
#define FUNC_NAME s_scm_sloppy_memv
{
for(; SCM_CONSP (lst); lst = SCM_CDR(lst))
--- 512,518 ----
GUILE_PROC (scm_sloppy_memv, "sloppy-memv", 2, 0, 0,
(SCM x, SCM lst),
! "See @code{sloppy-memq}.")
#define FUNC_NAME s_scm_sloppy_memv
{
for(; SCM_CONSP (lst); lst = SCM_CDR(lst))
***************
*** 507,513 ****
GUILE_PROC (scm_sloppy_member, "sloppy-member", 2, 0, 0,
(SCM x, SCM lst),
! "")
#define FUNC_NAME s_scm_sloppy_member
{
for(; SCM_CONSP (lst); lst = SCM_CDR(lst))
--- 527,533 ----
GUILE_PROC (scm_sloppy_member, "sloppy-member", 2, 0, 0,
(SCM x, SCM lst),
! "See @code{sloppy-memq}.")
#define FUNC_NAME s_scm_sloppy_member
{
for(; SCM_CONSP (lst); lst = SCM_CDR(lst))
***************
*** 523,529 ****
GUILE_PROC(scm_memq, "memq", 2, 0, 0,
(SCM x, SCM lst),
! "")
#define FUNC_NAME s_scm_memq
{
SCM answer;
--- 543,559 ----
GUILE_PROC(scm_memq, "memq", 2, 0, 0,
(SCM x, SCM lst),
! "@deffnx {essential procedure} memv obj list
! @deffnx {essential procedure} member obj list
!
! These procedures return the first sublist of @var{list} whose car is
! @var{obj}, where the sublists of @var{list} are the non-empty lists
! returned by @code{(list-tail @var{list} @var{k})} for @var{k} less
! than the length of @var{list}. If @var{obj} does not occur in
! @var{list}, then @code{#f} (not the empty list) is returned.
! @code{memq} uses @code{eq?} to compare @var{obj} with the elements of
! @var{list}, while @code{memv} uses @code{eqv?} and @code{member} uses
! @code{equal?}.")
#define FUNC_NAME s_scm_memq
{
SCM answer;
***************
*** 537,543 ****
GUILE_PROC(scm_memv, "memv", 2, 0, 0,
(SCM x, SCM lst),
! "")
#define FUNC_NAME s_scm_memv
{
SCM answer;
--- 567,573 ----
GUILE_PROC(scm_memv, "memv", 2, 0, 0,
(SCM x, SCM lst),
! "See @code{memq}.")
#define FUNC_NAME s_scm_memv
{
SCM answer;
***************
*** 550,556 ****
GUILE_PROC(scm_member, "member", 2, 0, 0,
(SCM x, SCM lst),
! "")
#define FUNC_NAME s_scm_member
{
SCM answer;
--- 580,586 ----
GUILE_PROC(scm_member, "member", 2, 0, 0,
(SCM x, SCM lst),
! "See @code{memq}.")
#define FUNC_NAME s_scm_member
{
SCM answer;
***************
*** 596,602 ****
GUILE_PROC(scm_delv_x, "delv!", 2, 0, 0,
(SCM item, SCM lst),
! "")
#define FUNC_NAME s_scm_delv_x
{
SCM walk;
--- 626,632 ----
GUILE_PROC(scm_delv_x, "delv!", 2, 0, 0,
(SCM item, SCM lst),
! "See @code{delq!}.")
#define FUNC_NAME s_scm_delv_x
{
SCM walk;
***************
*** 620,626 ****
GUILE_PROC(scm_delete_x, "delete!", 2, 0, 0,
(SCM item, SCM lst),
! "")
#define FUNC_NAME s_scm_delete_x
{
SCM walk;
--- 650,656 ----
GUILE_PROC(scm_delete_x, "delete!", 2, 0, 0,
(SCM item, SCM lst),
! "See @code{delq!}.")
#define FUNC_NAME s_scm_delete_x
{
SCM walk;
***************
*** 661,667 ****
GUILE_PROC (scm_delv, "delv", 2, 0, 0,
(SCM item, SCM lst),
! "")
#define FUNC_NAME s_scm_delv
{
SCM copy = scm_list_copy (lst);
--- 691,697 ----
GUILE_PROC (scm_delv, "delv", 2, 0, 0,
(SCM item, SCM lst),
! "See @code{delq}.")
#define FUNC_NAME s_scm_delv
{
SCM copy = scm_list_copy (lst);
***************
*** 671,677 ****
GUILE_PROC (scm_delete, "delete", 2, 0, 0,
(SCM item, SCM lst),
! "")
#define FUNC_NAME s_scm_delete
{
SCM copy = scm_list_copy (lst);
--- 701,707 ----
GUILE_PROC (scm_delete, "delete", 2, 0, 0,
(SCM item, SCM lst),
! "See @code{delq}.")
#define FUNC_NAME s_scm_delete
{
SCM copy = scm_list_copy (lst);
***************
*** 682,688 ****
GUILE_PROC(scm_delq1_x, "delq1!", 2, 0, 0,
(SCM item, SCM lst),
! "")
#define FUNC_NAME s_scm_delq1_x
{
SCM walk;
--- 712,724 ----
GUILE_PROC(scm_delq1_x, "delq1!", 2, 0, 0,
(SCM item, SCM lst),
! "@deffnx primitive delv1! item lst
! @deffnx primitive delete1! item lst
! These procedures are like @code{delq!}, @code{delv!} and
! @code{delete!} but they delete at most one element from the @var{lst}.
! Caveat evaluator: Like other destructive list functions, these
! functions cannot modify the binding of @var{lst}, and so cannot be
! used to delete the first element of @var{lst} destructively.")
#define FUNC_NAME s_scm_delq1_x
{
SCM walk;
***************
*** 708,714 ****
GUILE_PROC(scm_delv1_x, "delv1!", 2, 0, 0,
(SCM item, SCM lst),
! "")
#define FUNC_NAME s_scm_delv1_x
{
SCM walk;
--- 744,750 ----
GUILE_PROC(scm_delv1_x, "delv1!", 2, 0, 0,
(SCM item, SCM lst),
! "See @code{delq1!}.")
#define FUNC_NAME s_scm_delv1_x
{
SCM walk;
***************
*** 734,740 ****
GUILE_PROC(scm_delete1_x, "delete1!", 2, 0, 0,
(SCM item, SCM lst),
! "")
#define FUNC_NAME s_scm_delete1_x
{
SCM walk;
--- 770,776 ----
GUILE_PROC(scm_delete1_x, "delete1!", 2, 0, 0,
(SCM item, SCM lst),
! "See @code{delq1!}.")
#define FUNC_NAME s_scm_delete1_x
{
SCM walk;
Index: boolean.c
===================================================================
RCS file: /cvs/guile/guile/guile-core/libguile/boolean.c,v
retrieving revision 1.7
diff -c -r1.7 boolean.c
*** boolean.c 1999/12/13 00:44:10 1.7
--- boolean.c 1999/12/18 18:51:49
***************
*** 54,60 ****
GUILE_PROC(scm_not, "not", 1, 0, 0,
(SCM x),
! "")
#define FUNC_NAME s_scm_not
{
return SCM_BOOL(SCM_FALSEP(x));
--- 54,61 ----
GUILE_PROC(scm_not, "not", 1, 0, 0,
(SCM x),
! "@samp{Not} returns @t{#t} if @var{obj} is false, and returns
! @t{#f} otherwise.")
#define FUNC_NAME s_scm_not
{
return SCM_BOOL(SCM_FALSEP(x));
***************
*** 64,70 ****
GUILE_PROC(scm_boolean_p, "boolean?", 1, 0, 0,
(SCM obj),
! "")
#define FUNC_NAME s_scm_boolean_p
{
return SCM_BOOL(SCM_BOOL_F == obj || SCM_BOOL_T == obj);
--- 65,72 ----
GUILE_PROC(scm_boolean_p, "boolean?", 1, 0, 0,
(SCM obj),
! "@samp{Boolean?} returns @t{#t} if @var{obj} is either @t{#t} or
! @t{#f} and returns @t{#f} otherwise.")
#define FUNC_NAME s_scm_boolean_p
{
return SCM_BOOL(SCM_BOOL_F == obj || SCM_BOOL_T == obj);