From: Greg J. Badros Date: Mon, 14 Feb 2000 03:13:19 +0000 (+0000) Subject: * arbiters.c, eq.c, gc.c, guardians.c, list.c, ports.c, print.c, X-Git-Url: https://git.hcoop.net/bpt/guile.git/commitdiff_plain/b450f07086e27f6bb428a5d8e6f17fa997073c26 * arbiters.c, eq.c, gc.c, guardians.c, list.c, ports.c, print.c, regex-posix.c, scmsigs.c, stime.c, strings.c, variable.c, stime.c, strings.c, variable.c: Added lots of documentation, cleaned up some existing documentation. Occasionally changed formal params to match docs. Also folded an #ifdef into the inners of a primitive instead of having two copies of the primitive (`get-internal-real-time', from stime.c) --- diff --git a/libguile/arbiters.c b/libguile/arbiters.c index d1d9e3041..c4df49ab8 100644 --- a/libguile/arbiters.c +++ b/libguile/arbiters.c @@ -76,7 +76,8 @@ prinarb (SCM exp, SCM port, scm_print_state *pstate) SCM_DEFINE (scm_make_arbiter, "make-arbiter", 1, 0, 0, (SCM name), -"") +"Returns an object of type arbiter and name name. Its state is initially unlocked.\n" +"Arbiters are a way to achieve process synchronization.") #define FUNC_NAME s_scm_make_arbiter { SCM_RETURN_NEWSMOB (scm_tc16_arbiter, name); @@ -85,7 +86,7 @@ SCM_DEFINE (scm_make_arbiter, "make-arbiter", 1, 0, 0, SCM_DEFINE (scm_try_arbiter, "try-arbiter", 1, 0, 0, (SCM arb), -"") +"Returns #t and locks arbiter if arbiter was unlocked. Otherwise, returns #f.") #define FUNC_NAME s_scm_try_arbiter { SCM_VALIDATE_SMOB (1,arb,arbiter); @@ -105,7 +106,7 @@ SCM_DEFINE (scm_try_arbiter, "try-arbiter", 1, 0, 0, SCM_DEFINE (scm_release_arbiter, "release-arbiter", 1, 0, 0, (SCM arb), -"") +"Returns #t and unlocks arbiter if arbiter was locked. Otherwise, returns #f.") #define FUNC_NAME s_scm_release_arbiter { SCM_VALIDATE_SMOB (1,arb,arbiter); diff --git a/libguile/eq.c b/libguile/eq.c index 47823ca35..6ca1156da 100644 --- a/libguile/eq.c +++ b/libguile/eq.c @@ -59,8 +59,7 @@ SCM_DEFINE1 (scm_eq_p, "eq?", scm_tc7_rpsubr, "Return #t iff X references the same object as Y.\n" "`eq?' is similar to `eqv?' except that in some cases\n" "it is capable of discerning distinctions finer than\n" - "those detectable by `eqv?'.\n" - "") + "those detectable by `eqv?'.\n") #define FUNC_NAME s_scm_eq_p { return SCM_BOOL(x==y); @@ -104,8 +103,7 @@ SCM_DEFINE1 (scm_equal_p, "equal?", scm_tc7_rpsubr, "strings, applying `eqv?' on other objects such as numbers and\n" "symbols. A rule of thumb is that objects are generally `equal?'\n" "if they print the same. `Equal?' may fail to terminate if its\n" - "arguments are circular data structures.\n" - "") + "arguments are circular data structures.\n") #define FUNC_NAME s_scm_equal_p { SCM_CHECK_STACK; diff --git a/libguile/gc.c b/libguile/gc.c index b0fca6c75..70bc24886 100644 --- a/libguile/gc.c +++ b/libguile/gc.c @@ -245,7 +245,8 @@ which_seg (SCM cell) SCM_DEFINE (scm_map_free_list, "map-free-list", 0, 0, 0, (), -"") + "Print debugging information about the free-list.\n" + "`map-free-list' is only included in GUILE_DEBUG_FREELIST builds of Guile.") #define FUNC_NAME s_scm_map_free_list { int last_seg = -1, count = 0; diff --git a/libguile/guardians.c b/libguile/guardians.c index 7653285ca..a43734361 100644 --- a/libguile/guardians.c +++ b/libguile/guardians.c @@ -159,8 +159,7 @@ SCM_DEFINE (scm_make_guardian, "make-guardian", 0, 0, 0, "See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)\n" "\"Guardians in a Generation-Based Garbage Collector\".\n" "ACM SIGPLAN Conference on Programming Language Design\n" - "and Implementation, June 1993\n" - "") + "and Implementation, June 1993\n.") #define FUNC_NAME s_scm_make_guardian { SCM cclo = scm_makcclo (guard1, 2L); diff --git a/libguile/list.c b/libguile/list.c index 916d0eb7d..16c52c71f 100644 --- a/libguile/list.c +++ b/libguile/list.c @@ -81,7 +81,7 @@ scm_listify (SCM elt, ...) SCM_DEFINE (scm_list, "list", 0, 0, 1, (SCM objs), -"") + "Return a list containing OBJS, the arguments to `list'.") #define FUNC_NAME s_scm_list { return objs; @@ -114,7 +114,7 @@ SCM_DEFINE (scm_list_star, "list*", 1, 0, 1, SCM_DEFINE (scm_null_p, "null?", 1, 0, 0, (SCM x), -"") + "Return #t iff X is the empty list, else #f.") #define FUNC_NAME s_scm_null_p { return SCM_BOOL (SCM_NULLP (x)); @@ -124,7 +124,7 @@ SCM_DEFINE (scm_null_p, "null?", 1, 0, 0, SCM_DEFINE (scm_list_p, "list?", 1, 0, 0, (SCM x), -"") + "Return #t iff X is a proper list, else #f.") #define FUNC_NAME s_scm_list_p { return SCM_BOOL (scm_ilength (x) >= 0); @@ -165,7 +165,7 @@ scm_ilength(SCM sx) SCM_DEFINE (scm_length, "length", 1, 0, 0, (SCM lst), -"") + "Return the number of elements in list LST.") #define FUNC_NAME s_scm_length { int i; @@ -214,7 +214,7 @@ SCM_DEFINE (scm_append, "append", 0, 0, 1, SCM_DEFINE (scm_append_x, "append!", 0, 0, 1, (SCM args), -"") + "") #define FUNC_NAME s_scm_append_x { SCM arg; @@ -263,7 +263,7 @@ SCM_DEFINE (scm_last_pair, "last-pair", 1, 0, 0, SCM_DEFINE (scm_reverse, "reverse", 1, 0, 0, (SCM lst), - "") + "Return a new list that contains the elements of LST but in reverse order.") #define FUNC_NAME s_scm_reverse { SCM result = SCM_EOL; @@ -323,7 +323,7 @@ SCM_DEFINE (scm_reverse_x, "reverse!", 1, 1, 0, SCM_DEFINE (scm_list_ref, "list-ref", 2, 0, 0, (SCM lst, SCM k), - "") + "Return the Kth element from list LST.") #define FUNC_NAME s_scm_list_ref { register long i; @@ -459,12 +459,9 @@ SCM_DEFINE (scm_list_copy, "list-copy", 1, 0, 0, SCM_DEFINE (scm_sloppy_memq, "sloppy-memq", 2, 0, 0, (SCM x, SCM lst), - "@deffnx primitive sloppy-memv\n" - "@deffnx primitive sloppy-member\n" - "These procedures behave like @code{memq}, @code{memv} and @code{member}\n" - "(@pxref{Pairs and Lists,,,r4rs, The Revised^4 Report on Scheme}), but do\n" - "not perform any type or error checking. Their use is recommended only\n" - "in writing Guile internals, not for high-level Scheme programs.") + "This procedure behaves like @code{memq}, but does no type or error checking.\n" + "Its use is recommended only in writing Guile internals,\n" + "not for high-level Scheme programs.") #define FUNC_NAME s_scm_sloppy_memq { for(; SCM_CONSP (lst); lst = SCM_CDR(lst)) @@ -479,7 +476,9 @@ SCM_DEFINE (scm_sloppy_memq, "sloppy-memq", 2, 0, 0, SCM_DEFINE (scm_sloppy_memv, "sloppy-memv", 2, 0, 0, (SCM x, SCM lst), - "") + "This procedure behaves like @code{memv}, but does no type or error checking.\n" + "Its use is recommended only in writing Guile internals,\n" + "not for high-level Scheme programs.") #define FUNC_NAME s_scm_sloppy_memv { for(; SCM_CONSP (lst); lst = SCM_CDR(lst)) @@ -494,7 +493,9 @@ SCM_DEFINE (scm_sloppy_memv, "sloppy-memv", 2, 0, 0, SCM_DEFINE (scm_sloppy_member, "sloppy-member", 2, 0, 0, (SCM x, SCM lst), - "") + "This procedure behaves like @code{member}, but does no type or error checking.\n" + "Its use is recommended only in writing Guile internals,\n" + "not for high-level Scheme programs.") #define FUNC_NAME s_scm_sloppy_member { for(; SCM_CONSP (lst); lst = SCM_CDR(lst)) @@ -510,7 +511,11 @@ SCM_DEFINE (scm_sloppy_member, "sloppy-member", 2, 0, 0, SCM_DEFINE (scm_memq, "memq", 2, 0, 0, (SCM x, SCM lst), - "") + "Return the first sublist of LST whose car is `eq?' to X\n" + "where the sublists of LST are the non-empty lists returned\n" + "by `(list-tail LST K)' for K less than the length of LST. If\n" + "X does not occur in LST, then `#f' (not the empty list) is\n" + "returned.") #define FUNC_NAME s_scm_memq { SCM answer; @@ -524,7 +529,11 @@ SCM_DEFINE (scm_memq, "memq", 2, 0, 0, SCM_DEFINE (scm_memv, "memv", 2, 0, 0, (SCM x, SCM lst), - "") + "Return the first sublist of LST whose car is `eqv?' to X\n" + "where the sublists of LST are the non-empty lists returned\n" + "by `(list-tail LST K)' for K less than the length of LST. If\n" + "X does not occur in LST, then `#f' (not the empty list) is\n" + "returned.") #define FUNC_NAME s_scm_memv { SCM answer; @@ -537,7 +546,11 @@ SCM_DEFINE (scm_memv, "memv", 2, 0, 0, SCM_DEFINE (scm_member, "member", 2, 0, 0, (SCM x, SCM lst), - "") + "Return the first sublist of LST whose car is `equal?' to X\n" + "where the sublists of LST are the non-empty lists returned\n" + "by `(list-tail LST K)' for K less than the length of LST. If\n" + "X does not occur in LST, then `#f' (not the empty list) is\n" + "returned.") #define FUNC_NAME s_scm_member { SCM answer; @@ -583,7 +596,7 @@ SCM_DEFINE (scm_delq_x, "delq!", 2, 0, 0, SCM_DEFINE (scm_delv_x, "delv!", 2, 0, 0, (SCM item, SCM lst), - "") + "Destructively remove all elements from LST that are `eqv?' to ITEM.") #define FUNC_NAME s_scm_delv_x { SCM walk; @@ -607,7 +620,7 @@ SCM_DEFINE (scm_delv_x, "delv!", 2, 0, 0, SCM_DEFINE (scm_delete_x, "delete!", 2, 0, 0, (SCM item, SCM lst), - "") + "Destructively remove all elements from LST that are `equal?' to ITEM.") #define FUNC_NAME s_scm_delete_x { SCM walk; @@ -633,12 +646,10 @@ SCM_DEFINE (scm_delete_x, "delete!", 2, 0, 0, SCM_DEFINE (scm_delq, "delq", 2, 0, 0, (SCM item, SCM lst), - "@deffnx primitive delv item lst\n" - "@deffnx primitive delete item lst\n" - "Return a newly-created copy of @var{lst} with @var{item} removed. These\n" - "procedures mirror @code{memq}, @code{memv} and @code{member}:\n" + "Return a newly-created copy of @var{lst} with elements `eq?' to @var{item} removed.\n" + "This procedure mirrors @code{memq}:\n" "@code{delq} compares elements of @var{lst} against @var{item} with\n" - "@code{eq?}, @code{delv} uses @code{eqv?} and @code{delete} uses @code{equal?}") + "@code{eq?}.") #define FUNC_NAME s_scm_delq { SCM copy = scm_list_copy (lst); @@ -648,7 +659,10 @@ SCM_DEFINE (scm_delq, "delq", 2, 0, 0, SCM_DEFINE (scm_delv, "delv", 2, 0, 0, (SCM item, SCM lst), - "") + "Return a newly-created copy of @var{lst} with elements `eqv?' to @var{item} removed.\n" + "This procedure mirrors @code{memv}:\n" + "@code{delv} compares elements of @var{lst} against @var{item} with\n" + "@code{eqv?}.") #define FUNC_NAME s_scm_delv { SCM copy = scm_list_copy (lst); @@ -658,7 +672,10 @@ SCM_DEFINE (scm_delv, "delv", 2, 0, 0, SCM_DEFINE (scm_delete, "delete", 2, 0, 0, (SCM item, SCM lst), - "") + "Return a newly-created copy of @var{lst} with elements `equal?' to @var{item} removed.\n" + "This procedure mirrors @code{member}:\n" + "@code{delete} compares elements of @var{lst} against @var{item} with\n" + "@code{equal?}.") #define FUNC_NAME s_scm_delete { SCM copy = scm_list_copy (lst); diff --git a/libguile/ports.c b/libguile/ports.c index e3346c9be..496d5d124 100644 --- a/libguile/ports.c +++ b/libguile/ports.c @@ -332,7 +332,8 @@ SCM_DEFINE (scm_current_error_port, "current-error-port", 0, 0, 0, SCM_DEFINE (scm_current_load_port, "current-load-port", 0, 0, 0, (), - "") + "Return the current-load-port.\n" + "The load port is used internally by `primitive-load'.") #define FUNC_NAME s_scm_current_load_port { return scm_cur_loadp; @@ -358,7 +359,7 @@ SCM_DEFINE (scm_set_current_input_port, "set-current-input-port", 1, 0, 0, SCM_DEFINE (scm_set_current_output_port, "set-current-output-port", 1, 0, 0, (SCM port), - "") + "Set the current default output port to PORT.") #define FUNC_NAME s_scm_set_current_output_port { SCM ooutp = scm_cur_outp; @@ -372,7 +373,7 @@ SCM_DEFINE (scm_set_current_output_port, "set-current-output-port", 1, 0, 0, SCM_DEFINE (scm_set_current_error_port, "set-current-error-port", 1, 0, 0, (SCM port), - "") + "Set the current default error port to PORT.") #define FUNC_NAME s_scm_set_current_error_port { SCM oerrp = scm_cur_errp; @@ -455,26 +456,26 @@ scm_remove_from_port_table (SCM port) } #ifdef GUILE_DEBUG -/* Undocumented functions for debugging. */ -/* Return the number of ports in the table. */ +/* Functions for debugging. */ SCM_DEFINE (scm_pt_size, "pt-size", 0, 0, 0, - (), - "") + (), + "Returns the number of ports in the port table.\n" + "`pt-size' is only included in GUILE_DEBUG builds.") #define FUNC_NAME s_scm_pt_size { return SCM_MAKINUM (scm_port_table_size); } #undef FUNC_NAME -/* Return the ith member of the port table. */ SCM_DEFINE (scm_pt_member, "pt-member", 1, 0, 0, - (SCM member), - "") + (SCM index), + "Returns the port at INDEX in the port table.\n" + "`pt-member' is only included in GUILE_DEBUG builds.") #define FUNC_NAME s_scm_pt_member { int i; - SCM_VALIDATE_INUM_COPY (1,member,i); + SCM_VALIDATE_INUM_COPY (1,index,i); if (i < 0 || i >= scm_port_table_size) return SCM_BOOL_F; else @@ -515,7 +516,7 @@ SCM_DEFINE (scm_port_revealed, "port-revealed", 1, 0, 0, /* Set the revealed count for a port. */ SCM_DEFINE (scm_set_port_revealed_x, "set-port-revealed!", 2, 0, 0, (SCM port, SCM rcount), - "Sets the revealed count for a port to a given value. \n" + "Sets the revealed count for a port to a given value.\n" "The return value is unspecified.") #define FUNC_NAME s_scm_set_port_revealed_x { @@ -1158,7 +1159,7 @@ SCM_DEFINE (scm_truncate_file, "truncate-file", 1, 1, 0, SCM_DEFINE (scm_port_line, "port-line", 1, 0, 0, (SCM port), - "") + "Return the current line number for PORT.") #define FUNC_NAME s_scm_port_line { port = SCM_COERCE_OUTPORT (port); @@ -1169,7 +1170,7 @@ SCM_DEFINE (scm_port_line, "port-line", 1, 0, 0, SCM_DEFINE (scm_set_port_line_x, "set-port-line!", 2, 0, 0, (SCM port, SCM line), - "") + "Set the current line number for PORT to LINE.") #define FUNC_NAME s_scm_set_port_line_x { port = SCM_COERCE_OUTPORT (port); diff --git a/libguile/print.c b/libguile/print.c index 746bcb5aa..ee1f85aa7 100644 --- a/libguile/print.c +++ b/libguile/print.c @@ -187,7 +187,8 @@ static SCM print_state_pool; SCM_DEFINE (scm_current_pstate, "current-pstate", 0, 0, 0, (), -"") + "Return the current-pstate--the `cadr' of the print_state_pool.\n" + "`current-pstate' is only included in GUILE_DEBUG builds.") #define FUNC_NAME s_scm_current_pstate { return SCM_CADR (print_state_pool); @@ -998,8 +999,8 @@ SCM_DEFINE (scm_simple_format, "simple-format", 2, 0, 1, SCM_DEFINE (scm_newline, "newline", 0, 1, 0, - (SCM port), - "") + (SCM port), + "Send a newline to PORT.") #define FUNC_NAME s_scm_newline { if (SCM_UNBNDP (port)) @@ -1013,8 +1014,8 @@ SCM_DEFINE (scm_newline, "newline", 0, 1, 0, #undef FUNC_NAME SCM_DEFINE (scm_write_char, "write-char", 1, 1, 0, - (SCM chr, SCM port), - "") + (SCM chr, SCM port), + "Send character CHR to PORT.") #define FUNC_NAME s_scm_write_char { if (SCM_UNBNDP (port)) diff --git a/libguile/regex-posix.c b/libguile/regex-posix.c index f43a26d06..dcbe85518 100644 --- a/libguile/regex-posix.c +++ b/libguile/regex-posix.c @@ -176,8 +176,7 @@ SCM_DEFINE (scm_make_regexp, "make-regexp", 1, 0, 1, "call to @code{make-regexp} includes both @code{regexp/basic} and\n" "@code{regexp/extended} flags, the one which comes last will override\n" "the earlier one.\n" - "@end table\n" - "") + "@end table\n") #define FUNC_NAME s_scm_make_regexp { SCM flag; diff --git a/libguile/scmsigs.c b/libguile/scmsigs.c index 31952da0c..5a584bc44 100644 --- a/libguile/scmsigs.c +++ b/libguile/scmsigs.c @@ -418,7 +418,8 @@ SCM_DEFINE (scm_sleep, "sleep", 1, 0, 0, #if defined(USE_THREADS) || defined(HAVE_USLEEP) SCM_DEFINE (scm_usleep, "usleep", 1, 0, 0, (SCM i), - "") + "Sleep for I microseconds.\n" + "`usleep' is not available on all platforms.") #define FUNC_NAME s_scm_usleep { SCM_VALIDATE_INUM_MIN (1,i,0); diff --git a/libguile/stime.c b/libguile/stime.c index b28daab04..d6bcb14b5 100644 --- a/libguile/stime.c +++ b/libguile/stime.c @@ -126,14 +126,17 @@ long mytime() extern int errno; #ifdef HAVE_FTIME - struct timeb scm_your_base = {0}; +#else +timet scm_your_base = 0; +#endif SCM_DEFINE (scm_get_internal_real_time, "get-internal-real-time", 0, 0, 0, (), "Returns the number of time units since the interpreter was started.") #define FUNC_NAME s_scm_get_internal_real_time { +#ifdef HAVE_FTIME struct timeb time_buffer; SCM tmp; @@ -145,24 +148,12 @@ SCM_DEFINE (scm_get_internal_real_time, "get-internal-real-time", 0, 0, 0, SCM_MAKINUM (time_buffer.time))); return scm_quotient (scm_product (tmp, SCM_MAKINUM (CLKTCK)), SCM_MAKINUM (1000)); -} -#undef FUNC_NAME - - #else - -timet scm_your_base = 0; - -SCM_DEFINE (scm_get_internal_real_time, "get-internal-real-time", 0, 0, 0, - (), - "") -#define FUNC_NAME s_scm_get_internal_real_time -{ return scm_long2num((time((timet*)0) - scm_your_base) * (int)CLKTCK); +#endif /* HAVE_FTIME */ } #undef FUNC_NAME -#endif #ifdef HAVE_TIMES SCM_DEFINE (scm_times, "times", 0, 0, 0, diff --git a/libguile/strings.c b/libguile/strings.c index daf1cafe3..530073a40 100644 --- a/libguile/strings.c +++ b/libguile/strings.c @@ -218,8 +218,7 @@ SCM_DEFINE (scm_make_string, "make-string", 1, 1, 0, "Returns a newly allocated string of\n" "length K. If CHR is given, then all elements of the string\n" "are initialized to CHR, otherwise the contents of the\n" - "STRING are unspecified.\n" - "") + "STRING are unspecified.\n") #define FUNC_NAME s_scm_make_string { SCM res; diff --git a/libguile/variable.c b/libguile/variable.c index f74a58d85..19059988b 100644 --- a/libguile/variable.c +++ b/libguile/variable.c @@ -105,8 +105,7 @@ SCM_DEFINE (scm_make_variable, "make-variable", 1, 1, 0, "If given, uses NAME-HINT as its internal (debugging)\n" "name, otherwise just treat it as an anonymous variable.\n" "Remember, of course, that multiple bindings to the same\n" - "variable may exist, so NAME-HINT is just that---a hint.\n" - "") + "variable may exist, so NAME-HINT is just that---a hint.\n") #define FUNC_NAME s_scm_make_variable { SCM val_cell; @@ -130,8 +129,7 @@ SCM_DEFINE (scm_make_undefined_variable, "make-undefined-variable", 0, 1, 0, "If given, uses NAME-HINT as its internal (debugging)\n" "name, otherwise just treat it as an anonymous variable.\n" "Remember, of course, that multiple bindings to the same\n" - "variable may exist, so NAME-HINT is just that---a hint.\n" - "") + "variable may exist, so NAME-HINT is just that---a hint.\n") #define FUNC_NAME s_scm_make_undefined_variable { SCM vcell; @@ -177,8 +175,7 @@ SCM_DEFINE (scm_variable_set_x, "variable-set!", 2, 0, 0, (SCM var, SCM val), "Set the value of the variable VAR to VAL.\n" "VAR must be a variable object, VAL can be any value.\n" - "Returns an unspecified value.\n" - "") + "Returns an unspecified value.\n") #define FUNC_NAME s_scm_variable_set_x { SCM_VALIDATE_VARIABLE (1,var); @@ -192,8 +189,7 @@ SCM_DEFINE (scm_builtin_variable, "builtin-variable", 1, 0, 0, (SCM name), "Return the built-in variable with the name NAME.\n" "NAME must be a symbol (not a string).\n" - "Then use `variable-ref' to access its value.\n" - "") + "Then use `variable-ref' to access its value.\n") #define FUNC_NAME s_scm_builtin_variable { SCM vcell; @@ -221,8 +217,7 @@ SCM_DEFINE (scm_builtin_variable, "builtin-variable", 1, 0, 0, SCM_DEFINE (scm_variable_bound_p, "variable-bound?", 1, 0, 0, (SCM var), "Return #t iff VAR is bound to a value.\n" - "Throws an error if VAR is not a variable object.\n" - "") + "Throws an error if VAR is not a variable object.\n") #define FUNC_NAME s_scm_variable_bound_p { SCM_VALIDATE_VARIABLE (1,var);