diff options
| author | Martin Grabmüller <mgrabmue@cs.tu-berlin.de> | 2001-04-03 13:19:05 +0000 |
|---|---|---|
| committer | Martin Grabmüller <mgrabmue@cs.tu-berlin.de> | 2001-04-03 13:19:05 +0000 |
| commit | 1e6808ea204cef454e41af1e2f309100ab99e9e1 (patch) | |
| tree | fb93c3098d7dd4e7af175dbde98b5dc41dcd7c0d /libguile | |
| parent | ae9f3a15826847d280f69b179c2e09776892a9c6 (diff) | |
| download | guile-1e6808ea204cef454e41af1e2f309100ab99e9e1.tar.gz | |
Correct, update, improve and clean up a lot of docstrings in order to make
the documentation much more consistent.
Diffstat (limited to 'libguile')
41 files changed, 1133 insertions, 949 deletions
diff --git a/libguile/ChangeLog b/libguile/ChangeLog index 2be583b3f..912745364 100644 --- a/libguile/ChangeLog +++ b/libguile/ChangeLog @@ -1,3 +1,109 @@ +2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de> + + The following changes make the documentation more consistent. + + * rdelim.c (scm_write_line), posix.c (scm_utime), ports.c + (scm_seek), net_db.c (scm_inet_aton, scm_inet_ntoa), + (scm_inet_netof, scm_lnaof, scm_inet_makeaddr), ioext.c + (scm_ftell): Changed @smalllisp ... @end smalllisp to @lisp + ... @end lisp. + + * vports.c (scm_make_soft_port), version.c (scm_version), unif.c + (scm_array_dimensions, scm_make_shared_array), + (scm_transpose_array, scm_enclose_array, scm_bit_count_star), + throw.c (scm_catch), struct.c (scm_make_vtable_vtable), strop.c + (scm_string_rindex, scm_string_index, scm_substring_fill_x), + (scm_string_null_p), strings.c (scm_read_only_string_p), root.c + (scm_call_with_dynamic_root), ramap.c (scm_array_index_map_x), + posix.c (scm_mknod), numbers.c (scm_logtest, scm_logbit_p), + macros.c (scm_makmmacro), list.c (scm_append), environments.c + (scm_environment_fold), dynwind.c (s_scm_dynamic_wind): Changed + @example ... @end example to @lisp ... @end lisp. + + * weaks.c (scm_weak_vector): Corrected docstring. + + * hashtab.c (scm_hashq_ref, scm_hashq_set_x, scm_hashq_remove_x), + (scm_hashv_ref, scm_hashv_set_x, scm_hashv_remove_x), + (scm_hash_ref, scm_hash_set_x, scm_hash_remove_x, scm_hashx_ref), + (scm_hashx_set_x, scm_hashx_get_handle), + (scm_hashx_create_handle_x), regex-posix.c (scm_make_regexp), + (scm_regexp_exec, scm_regexp_p), numbers.c (scm_logtest), + vectors.c (scm_vector_fill_x), strings.c + (scm_make_shared_substring), symbols.c (scm_string_to_symbol), + objprop.c (scm_set_object_properties_x): + (scm_set_object_property_x), throw.c (scm_catch, scm_lazy_catch), + strports.c (scm_call_with_input_string), ports.c + (scm_truncate_file), ioext.c (scm_ftell), ports.c (scm_seek), + list.c (scm_append_x), dynwind.c (scm_dynamic_wind), error.c + (scm_error_scm), vports.c (scm_make_soft_port), weaks.c + (scm_make_weak_vector,scm_weak_vector_p), + (scm_make_weak_key_hash_table, scm_make_weak_value_hash_table), + (scm_make_doubly_weak_hash_table, scm_weak_key_hash_table_p), + (scm_weak_value_hash_table_p, scm_doubly_weak_hash_table_p), + macros.c (scm_macro_type), dynl.c (scm_dynamic_link), + (scm_dynamic_unlink, scm_dynamic_call, scm_dynamic_args_call): + Made parameter names match documentation by renaming parameters + and/or fixing docstrings. + + * numbers.c (scm_ash): Corrected Texinfo markup. + + * strop.c (scm_string_index, scm_string_rindex), + (scm_substring_fill_x, scm_string_null_p): Removed `qdocs'. + + * vports.c (scm_make_soft_port), unif.c + (scm_uniform_vector_length, scm_array_p, scm_array_rank), + (scm_dimensions_to_uniform_array, scm_transpose_array), + (scm_array_in_bounds_p, scm_uniform_vector_ref), + (scm_bit_count, scm_bit_position, scm_bit_count_star), + (scm_array_to_list, scm_list_to_uniform_array), + (scm_array_prototype, symbols.c (scm_string_to_symbol), strports.c + (scm_open_input_string, scm_open_output_string), + (scm_get_output_string), strop.c (scm_string_copy), + (scm_string_fill_x), strings.c (scm_string_p, scm_string), stime.c + (scm_get_internal_real_time, scm_times), + (scm_get_internal_run_time, scm_current_time, scm_gettimeofday), + (scm_localtime, scm_gmtime), socket.c (scm_htons, scm_ntohs), + (scm_htonl, scm_ntohl, scm_socket, scm_socketpair), + (scm_getsockopt, scm_getsockname, scm_getpeername, scm_recvfrom), + simpos.c (scm_system), random.c (scm_random_uniform), + (scm_random_normal, scm_random_exp), ramap.c + (scm_array_equal_p), posix.c (scm_pipe, scm_getgroups), + (scm_status_exit_val, scm_status_term_sig, scm_status_stop_sig), + (scm_getppid, scm_getuid, scm_getgid, scm_geteuid, scm_getegid), + (scm_getpgrp, scm_ttyname, scm_ctermid, scm_tcgetpgrp, scm_uname), + (scm_environ, scm_tmpnam, scm_mkstemp, scm_access, scm_getpid), + (scm_setlocale), ports.c (scm_char_ready_p, scm_drain_input), + (scm_pt_size, scm_pt_member, scm_port_revealed, scm_port_mode), + (scm_close_port, scm_input_port_p, scm_output_port_p, scm_port_p), + (scm_port_closed_p, scm_eof_object_p, scm_read_char), + (scm_peek_char), pairs.c (scm_pair_p, scm_cons), numbers.c + (scm_logand, scm_logior, scm_logxor, scm_lognot), + (scm_integer_expt, scm_bit_extract, scm_logcount), + (scm_integer_length, scm_string_to_number, scm_inexact_to_exact), + net_db.c (scm_inet_netof, scm_lnaof), modules.c + (scm_interaction_environment), macros.c (scm_makacro), + (scm_makmacro, scm_makmmacro), keywords.c (scm_keyword_p), ioext.c + (scm_ftell, scm_dup_to_fdes, scm_fileno, scm_isatty_p), + (scm_fdopen, scm_fdes_to_ports), gc.c (scm_gc_stats), fluids.c + (scm_fluid_ref), filesys.c (scm_open_fdes), + (scm_stat, scm_directory_stream_p, scm_getcwd, scm_readlink): + Docstring correction: `Returns' -> `Return' + + * gc.c (scm_set_debug_cell_accesses_x): + (s_scm_gc_set_debug_check_freelist_x): + * fluids.c (scm_fluid_p): Added texinfo markup. + + * error.c (scm_strerror): Made docstring more precise. + + * vectors.c (scm_vector_p, scm_vector, scm_make_vector), + (scm_vector_to_list, _scm_vector_fill_x), symbols.c + (scm_symbol_p, scm_symbol_to_string), strorder.c + (scm_string_equal_p, scm_string_ci_equal_p, scm_string_less_p), + (scm_string_leq_p, scm_string_gr_p, scm_string_geq_p), + (scm_string_ci_less_p, scm_string_ci_leq_p, scm_string_ci_gr_p): + (scm_string_ci_geq_p), strop.c (scm_string_copy), + (scm_string_fill_x): Removed `(r5rs)' from docstrings. + 2001-04-01 Dirk Herrmann <D.Herrmann@tu-bs.de> * gc.c (MARK): Re-introduce a cheap sanity test for non debug diff --git a/libguile/dynl.c b/libguile/dynl.c index 1fa856cc6..e46866beb 100644 --- a/libguile/dynl.c +++ b/libguile/dynl.c @@ -350,18 +350,19 @@ dynl_obj_print (SCM exp, SCM port, scm_print_state *pstate) SCM_DEFINE (scm_dynamic_link, "dynamic-link", 1, 0, 0, - (SCM fname), - "Open the dynamic library @var{library-file}. A library handle\n" - "representing the opened library is returned; this handle should be used\n" - "as the @var{lib} argument to the following functions.") + (SCM filename), + "Open the dynamic library called @var{filename}. A library\n" + "handle representing the opened library is returned; this handle\n" + "should be used as the @var{dobj} argument to the following\n" + "functions.") #define FUNC_NAME s_scm_dynamic_link { void *handle; - SCM_VALIDATE_STRING (1, fname); - SCM_STRING_COERCE_0TERMINATION_X (fname); - handle = sysdep_dynl_link (SCM_STRING_CHARS (fname), FUNC_NAME); - SCM_RETURN_NEWSMOB2 (scm_tc16_dynamic_obj, SCM_UNPACK (fname), handle); + SCM_VALIDATE_STRING (1, filename); + SCM_STRING_COERCE_0TERMINATION_X (filename); + handle = sysdep_dynl_link (SCM_STRING_CHARS (filename), FUNC_NAME); + SCM_RETURN_NEWSMOB2 (scm_tc16_dynamic_obj, SCM_UNPACK (filename), handle); } #undef FUNC_NAME @@ -379,13 +380,10 @@ SCM_DEFINE (scm_dynamic_object_p, "dynamic-object?", 1, 0, 0, SCM_DEFINE (scm_dynamic_unlink, "dynamic-unlink", 1, 0, 0, (SCM dobj), - "Unlink the library represented by @var{library-handle},\n" - "and remove any imported symbols from the address space.\n" - "GJB:FIXME:DOC: 2nd version below:\n" "Unlink the indicated object file from the application. The\n" - "argument @var{dynobj} must have been obtained by a call to\n" + "argument @var{dobj} must have been obtained by a call to\n" "@code{dynamic-link}. After @code{dynamic-unlink} has been\n" - "called on @var{dynobj}, its content is no longer accessible.") + "called on @var{dobj}, its content is no longer accessible.") #define FUNC_NAME s_scm_dynamic_unlink { /*fixme* GC-problem */ @@ -442,19 +440,14 @@ SCM_DEFINE (scm_dynamic_func, "dynamic-func", 2, 0, 0, SCM_DEFINE (scm_dynamic_call, "dynamic-call", 2, 0, 0, (SCM func, SCM dobj), - "Call @var{lib-thunk}, a procedure of no arguments. If @var{lib-thunk}\n" - "is a string, it is assumed to be a symbol found in the dynamic library\n" - "@var{lib} and is fetched with @code{dynamic-func}. Otherwise, it should\n" - "be a function handle returned by a previous call to @code{dynamic-func}.\n" - "The return value is unspecified.\n" - "GJB:FIXME:DOC 2nd version below\n" - "Call the C function indicated by @var{function} and @var{dynobj}. The\n" - "function is passed no arguments and its return value is ignored. When\n" - "@var{function} is something returned by @code{dynamic-func}, call that\n" - "function and ignore @var{dynobj}. When @var{function} is a string (or\n" - "symbol, etc.), look it up in @var{dynobj}; this is equivalent to\n\n" + "Call the C function indicated by @var{func} and @var{dobj}.\n" + "The function is passed no arguments and its return value is\n" + "ignored. When @var{function} is something returned by\n" + "@code{dynamic-func}, call that function and ignore @var{dobj}.\n" + "When @var{func} is a string , look it up in @var{dynobj}; this\n" + "is equivalent to\n" "@smallexample\n" - "(dynamic-call (dynamic-func @var{function} @var{dynobj} #f))\n" + "(dynamic-call (dynamic-func @var{func} @var{dobj} #f))\n" "@end smallexample\n\n" "Interrupts are deferred while the C function is executing (with\n" "@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).") @@ -474,24 +467,18 @@ SCM_DEFINE (scm_dynamic_call, "dynamic-call", 2, 0, 0, SCM_DEFINE (scm_dynamic_args_call, "dynamic-args-call", 3, 0, 0, (SCM func, SCM dobj, SCM args), - "Call @var{proc}, a dynamically loaded function, passing it the argument\n" - "list @var{args} (a list of strings). As with @code{dynamic-call},\n" - "@var{proc} should be either a function handle or a string, in which case\n" - "it is first fetched from @var{lib} with @code{dynamic-func}.\n\n" - "@var{proc} is assumed to return an integer, which is used as the return\n" - "value from @code{dynamic-args-call}.\n\n" - "GJB:FIXME:DOC 2nd version below\n" - "Call the C function indicated by @var{function} and @var{dynobj}, just\n" - "like @code{dynamic-call}, but pass it some arguments and return its\n" - "return value. The C function is expected to take two arguments and\n" - "return an @code{int}, just like @code{main}:\n\n" + "Call the C function indicated by @var{func} and @var{dobj},\n" + "just like @code{dynamic-call}, but pass it some arguments and\n" + "return its return value. The C function is expected to take\n" + "two arguments and return an @code{int}, just like @code{main}:\n" "@smallexample\n" "int c_func (int argc, char **argv);\n" "@end smallexample\n\n" - "The parameter @var{args} must be a list of strings and is converted into\n" - "an array of @code{char *}. The array is passed in @var{argv} and its\n" - "size in @var{argc}. The return value is converted to a Scheme number\n" - "and returned from the call to @code{dynamic-args-call}.") + "The parameter @var{args} must be a list of strings and is\n" + "converted into an array of @code{char *}. The array is passed\n" + "in @var{argv} and its size in @var{argc}. The return value is\n" + "converted to a Scheme number and returned from the call to\n" + "@code{dynamic-args-call}.") #define FUNC_NAME s_scm_dynamic_args_call { int (*fptr) (int argc, char **argv); diff --git a/libguile/dynwind.c b/libguile/dynwind.c index 101107c70..c79097b61 100644 --- a/libguile/dynwind.c +++ b/libguile/dynwind.c @@ -70,60 +70,66 @@ SCM_DEFINE (scm_dynamic_wind, "dynamic-wind", 3, 0, 0, - (SCM thunk1, SCM thunk2, SCM thunk3), - "All three arguments must be 0-argument procedures.\n\n" - "@var{in-guard} is called, then @var{thunk}, then @var{out-guard}.\n\n" - "If, any time during the execution of @var{thunk}, the continuation\n" - "of the @code{dynamic-wind} expression is escaped non-locally, @var{out-guard}\n" - "is called. If the continuation of the dynamic-wind is re-entered,\n" - "@var{in-guard} is called. Thus @var{in-guard} and @var{out-guard} may\n" - "be called any number of times.\n\n" - "@example\n" + (SCM in_guard, SCM thunk, SCM out_guard), + "All three arguments must be 0-argument procedures.\n" + "@var{in_guard} is called, then @var{thunk}, then\n" + "@var{out_guard}.\n" + "\n" + "If, any time during the execution of @var{thunk}, the\n" + "continuation of the @code{dynamic_wind} expression is escaped\n" + "non-locally, @var{out_guard} is called. If the continuation of\n" + "the dynamic-wind is re-entered, @var{in_guard} is called. Thus\n" + "@var{in_guard} and @var{out_guard} may be called any number of\n" + "times.\n" + "@lisp\n" "(define x 'normal-binding)\n" - "@result{} x\n\n" + "@result{} x\n" "(define a-cont (call-with-current-continuation \n" " (lambda (escape)\n" " (let ((old-x x))\n" " (dynamic-wind\n" " ;; in-guard:\n" " ;;\n" - " (lambda () (set! x 'special-binding))\n\n" + " (lambda () (set! x 'special-binding))\n" + "\n" " ;; thunk\n" " ;;\n" " (lambda () (display x) (newline)\n" " (call-with-current-continuation escape)\n" " (display x) (newline)\n" - " x)\n\n" + " x)\n" + "\n" " ;; out-guard:\n" " ;;\n" - " (lambda () (set! x old-x)))))))\n\n" + " (lambda () (set! x old-x)))))))\n" + "\n" ";; Prints: \n" "special-binding\n" ";; Evaluates to:\n" - "@result{} a-cont\n\n" + "@result{} a-cont\n" "x\n" - "@result{} normal-binding\n\n" + "@result{} normal-binding\n" "(a-cont #f)\n" ";; Prints:\n" "special-binding\n" ";; Evaluates to:\n" - "@result{} a-cont ;; the value of the (define a-cont...)\n\n" + "@result{} a-cont ;; the value of the (define a-cont...)\n" "x\n" - "@result{} normal-binding\n\n" + "@result{} normal-binding\n" "a-cont\n" "@result{} special-binding\n" - "@end example\n") + "@end lisp") #define FUNC_NAME s_scm_dynamic_wind { SCM ans; - SCM_ASSERT (SCM_NFALSEP (scm_thunk_p (thunk3)), - thunk3, + SCM_ASSERT (SCM_NFALSEP (scm_thunk_p (out_guard)), + out_guard, SCM_ARG3, FUNC_NAME); - scm_apply (thunk1, SCM_EOL, SCM_EOL); - scm_dynwinds = scm_acons (thunk1, thunk3, scm_dynwinds); - ans = scm_apply (thunk2, SCM_EOL, SCM_EOL); + scm_apply (in_guard, SCM_EOL, SCM_EOL); + scm_dynwinds = scm_acons (in_guard, out_guard, scm_dynwinds); + ans = scm_apply (thunk, SCM_EOL, SCM_EOL); scm_dynwinds = SCM_CDR (scm_dynwinds); - scm_apply (thunk3, SCM_EOL, SCM_EOL); + scm_apply (out_guard, SCM_EOL, SCM_EOL); return ans; } #undef FUNC_NAME diff --git a/libguile/environments.c b/libguile/environments.c index aa14c3e0f..4facb164b 100644 --- a/libguile/environments.c +++ b/libguile/environments.c @@ -209,26 +209,26 @@ SCM_DEFINE (scm_environment_fold, "environment-fold", 3, 0, 0, "@var{init}.\n" "If @var{env} binds the symbol sym1 to the value val1, sym2 to\n" "val2, and so on, then this procedure computes:\n" - "@example\n" + "@lisp\n" " (proc sym1 val1\n" " (proc sym2 val2\n" " ...\n" " (proc symn valn\n" " init)))\n" - "@end example\n" + "@end lisp\n" "Each binding in @var{env} will be processed exactly once.\n" "@code{environment-fold} makes no guarantees about the order in\n" "which the bindings are processed.\n" "Here is a function which, given an environment, constructs an\n" "association list representing that environment's bindings,\n" "using environment-fold:\n" - "@example\n" + "@lisp\n" " (define (environment->alist env)\n" " (environment-fold env\n" " (lambda (sym val tail)\n" " (cons (cons sym val) tail))\n" " '()))\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_environment_fold { SCM_ASSERT (SCM_ENVIRONMENT_P (env), env, SCM_ARG1, FUNC_NAME); diff --git a/libguile/error.c b/libguile/error.c index 9073e2afe..d8fcc7aa8 100644 --- a/libguile/error.c +++ b/libguile/error.c @@ -98,18 +98,20 @@ scm_error (SCM key, const char *subr, const char *message, SCM args, SCM rest) /* Scheme interface to scm_error. */ SCM_DEFINE (scm_error_scm, "scm-error", 5, 0, 0, - (SCM key, SCM subr, SCM message, SCM args, SCM rest), - "Raise an error with key @var{key}. @var{subr} can be a string naming\n" - "the procedure associated with the error, or @code{#f}. @var{message}\n" - "is the error message string, possibly containing @code{~S} and @code{~A}\n" - "escapes. When an error is reported, these are replaced by formating the\n" - "corresponding members of @var{args}: @code{~A} (was @code{%s}) formats using @code{display}\n" - "and @code{~S} (was @code{%S}) formats using @code{write}. @var{data} is a\n" - "list or @code{#f} depending on @var{key}: if @var{key} is\n" - "@code{system-error} then it should be a list\n" - "containing the Unix @code{errno} value; If @var{key} is @code{signal} then\n" - "it should be a list containing the Unix signal number; otherwise it\n" - "will usually be @code{#f}.") + (SCM key, SCM subr, SCM message, SCM args, SCM data), + "Raise an error with key @var{key}. @var{subr} can be a string\n" + "naming the procedure associated with the error, or @code{#f}.\n" + "@var{message} is the error message string, possibly containing\n" + "@code{~S} and @code{~A} escapes. When an error is reported,\n" + "these are replaced by formatting the corresponding members of\n" + "@var{args}: @code{~A} (was @code{%s} in older versions of\n" + "Guile) formats using @code{display} and @code{~S} (was\n" + "@code{%S}) formats using @code{write}. @var{data} is a list or\n" + "@code{#f} depending on @var{key}: if @var{key} is\n" + "@code{system-error} then it should be a list containing the\n" + "Unix @code{errno} value; If @var{key} is @code{signal} then it\n" + "should be a list containing the Unix signal number; otherwise\n" + "it will usually be @code{#f}.") #define FUNC_NAME s_scm_error_scm { char *szSubr; @@ -143,14 +145,15 @@ SCM_DEFINE (scm_error_scm, "scm-error", 5, 0, 0, szMessage = SCM_STRING_CHARS (message); } - scm_error (key, szSubr, szMessage, args, rest); + scm_error (key, szSubr, szMessage, args, data); /* not reached. */ } #undef FUNC_NAME SCM_DEFINE (scm_strerror, "strerror", 1, 0, 0, (SCM err), - "Returns the Unix error message corresponding to @var{err}, an integer.") + "Return the Unix error message corresponding to @var{err}, which\n" + "must be an integer value.") #define FUNC_NAME s_scm_strerror { SCM_VALIDATE_INUM (1,err); diff --git a/libguile/filesys.c b/libguile/filesys.c index e034f1fb2..48f8dfa67 100644 --- a/libguile/filesys.c +++ b/libguile/filesys.c @@ -233,8 +233,8 @@ SCM_DEFINE (scm_umask, "umask", 0, 1, 0, SCM_DEFINE (scm_open_fdes, "open-fdes", 2, 1, 0, (SCM path, SCM flags, SCM mode), - "Similar to @code{open} but returns a file descriptor instead of a\n" - "port.") + "Similar to @code{open} but return a file descriptor instead of\n" + "a port.") #define FUNC_NAME s_scm_open_fdes { int fd; @@ -466,23 +466,26 @@ scm_stat2scm (struct stat *stat_temp) SCM_DEFINE (scm_stat, "stat", 1, 0, 0, (SCM object), - "Returns an object containing various information\n" - "about the file determined by @var{obj}.\n" - "@var{obj} can be a string containing a file name or a port or integer file\n" - "descriptor which is open on a file (in which case @code{fstat} is used\n" - "as the underlying system call).\n\n" - "The object returned by @code{stat} can be passed as a single parameter\n" - "to the following procedures, all of which return integers:\n\n" + "Return an object containing various information about the file\n" + "determined by @var{obj}. @var{obj} can be a string containing\n" + "a file name or a port or integer file descriptor which is open\n" + "on a file (in which case @code{fstat} is used as the underlying\n" + "system call).\n" + "\n" + "The object returned by @code{stat} can be passed as a single\n" + "parameter to the following procedures, all of which return\n" + "integers:\n" + "\n" "@table @code\n" "@item stat:dev\n" "The device containing the file.\n" "@item stat:ino\n" - "The file serial number, which distinguishes this file from all other\n" - "files on the same device.\n" + "The file serial number, which distinguishes this file from all\n" + "other files on the same device.\n" "@item stat:mode\n" - "The mode of the file. This includes file type information\n" - "and the file permission bits. See @code{stat:type} and @code{stat:perms}\n" - "below.\n" + "The mode of the file. This includes file type information and\n" + "the file permission bits. See @code{stat:type} and\n" + "@code{stat:perms} below.\n" "@item stat:nlink\n" "The number of hard links to the file.\n" "@item stat:uid\n" @@ -501,18 +504,21 @@ SCM_DEFINE (scm_stat, "stat", 1, 0, 0, "@item stat:ctime\n" "The last modification time for the attributes of the file.\n" "@item stat:blksize\n" - "The optimal block size for reading or writing the file, in bytes.\n" + "The optimal block size for reading or writing the file, in\n" + "bytes.\n" "@item stat:blocks\n" - "The amount of disk space that the file occupies measured in units of\n" - "512 byte blocks.\n" - "@end table\n\n" + "The amount of disk space that the file occupies measured in\n" + "units of 512 byte blocks.\n" + "@end table\n" + "\n" "In addition, the following procedures return the information\n" - "from stat:mode in a more convenient form:\n\n" + "from stat:mode in a more convenient form:\n" + "\n" "@table @code\n" "@item stat:type\n" "A symbol representing the type of file. Possible values are\n" - "regular, directory, symlink, block-special, char-special,\n" - "fifo, socket and unknown\n" + "regular, directory, symlink, block-special, char-special, fifo,\n" + "socket and unknown\n" "@item stat:perms\n" "An integer representing the access permission bits.\n" "@end table") @@ -685,8 +691,8 @@ scm_bits_t scm_tc16_dir; SCM_DEFINE (scm_directory_stream_p, "directory-stream?", 1, 0, 0, (SCM obj), - "Returns a boolean indicating whether @var{object} is a directory stream\n" - "as returned by @code{opendir}.") + "Return a boolean indicating whether @var{object} is a directory\n" + "stream as returned by @code{opendir}.") #define FUNC_NAME s_scm_directory_stream_p { return SCM_BOOL (SCM_DIRP (obj)); @@ -822,7 +828,7 @@ SCM_DEFINE (scm_chdir, "chdir", 1, 0, 0, #ifdef HAVE_GETCWD SCM_DEFINE (scm_getcwd, "getcwd", 0, 0, 0, (), - "Returns the name of the current working directory.") + "Return the name of the current working directory.") #define FUNC_NAME s_scm_getcwd { char *rv; @@ -1247,9 +1253,8 @@ SCM_DEFINE (scm_symlink, "symlink", 2, 0, 0, #ifdef HAVE_READLINK SCM_DEFINE (scm_readlink, "readlink", 1, 0, 0, (SCM path), - "Returns the value of the symbolic link named by\n" - "@var{path} (a string), i.e., the\n" - "file that the link points to.") + "Return the value of the symbolic link named by @var{path} (a\n" + "string), i.e., the file that the link points to.") #define FUNC_NAME s_scm_readlink { int rv; diff --git a/libguile/fluids.c b/libguile/fluids.c index a76b05c76..a24709828 100644 --- a/libguile/fluids.c +++ b/libguile/fluids.c @@ -138,7 +138,8 @@ SCM_DEFINE (scm_make_fluid, "make-fluid", 0, 0, 0, SCM_DEFINE (scm_fluid_p, "fluid?", 1, 0, 0, (SCM obj), - "Return #t iff @var{obj} is a fluid; otherwise, return #f.") + "Return @code{#t} iff @var{obj} is a fluid; otherwise, return\n" + "@code{#f}.") #define FUNC_NAME s_scm_fluid_p { return SCM_BOOL(SCM_FLUIDP (obj)); @@ -147,8 +148,9 @@ SCM_DEFINE (scm_fluid_p, "fluid?", 1, 0, 0, SCM_DEFINE (scm_fluid_ref, "fluid-ref", 1, 0, 0, (SCM fluid), - "Return the value associated with @var{fluid} in the current dynamic root.\n" - "If @var{fluid} has not been set, then this returns #f.") + "Return the value associated with @var{fluid} in the current\n" + "dynamic root. If @var{fluid} has not been set, then return\n" + "@code{#f}.") #define FUNC_NAME s_scm_fluid_ref { int n; diff --git a/libguile/fports.c b/libguile/fports.c index c062525f9..422d7d938 100644 --- a/libguile/fports.c +++ b/libguile/fports.c @@ -243,12 +243,12 @@ SCM_DEFINE (scm_file_port_p, "file-port?", 1, 0, 0, * Return the new port. */ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0, - (SCM filename, SCM modes), - "Open the file whose name is @var{string}, and return a port\n" + (SCM filename, SCM mode), + "Open the file whose name is @var{filename}, and return a port\n" "representing that file. The attributes of the port are\n" - "determined by the @var{mode} string. The way in \n" - "which this is interpreted is similar to C stdio:\n\n" - "The first character must be one of the following:\n\n" + "determined by the @var{mode} string. The way in which this is\n" + "interpreted is similar to C stdio. The first character must be\n" + "one of the following:\n" "@table @samp\n" "@item r\n" "Open an existing file for input.\n" @@ -256,48 +256,49 @@ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0, "Open a file for output, creating it if it doesn't already exist\n" "or removing its contents if it does.\n" "@item a\n" - "Open a file for output, creating it if it doesn't already exist.\n" - "All writes to the port will go to the end of the file.\n" + "Open a file for output, creating it if it doesn't already\n" + "exist. All writes to the port will go to the end of the file.\n" "The \"append mode\" can be turned off while the port is in use\n" "@pxref{Ports and File Descriptors, fcntl}\n" - "@end table\n\n" - "The following additional characters can be appended:\n\n" + "@end table\n" + "The following additional characters can be appended:\n" "@table @samp\n" "@item +\n" "Open the port for both input and output. E.g., @code{r+}: open\n" "an existing file for both input and output.\n" "@item 0\n" - "Create an \"unbuffered\" port. In this case input and output operations\n" - "are passed directly to the underlying port implementation without\n" - "additional buffering. This is likely to slow down I/O operations.\n" - "The buffering mode can be changed while a port is in use\n" - "@pxref{Ports and File Descriptors, setvbuf}\n" + "Create an \"unbuffered\" port. In this case input and output\n" + "operations are passed directly to the underlying port\n" + "implementation without additional buffering. This is likely to\n" + "slow down I/O operations. The buffering mode can be changed\n" + "while a port is in use @pxref{Ports and File Descriptors,\n" + "setvbuf}\n" "@item l\n" "Add line-buffering to the port. The port output buffer will be\n" "automatically flushed whenever a newline character is written.\n" - "@end table\n\n" - "In theory we could create read/write ports which were buffered in one\n" - "direction only. However this isn't included in the current interfaces.\n\n" - "If a file cannot be opened with the access requested,\n" - "@code{open-file} throws an exception.") + "@end table\n" + "In theory we could create read/write ports which were buffered\n" + "in one direction only. However this isn't included in the\n" + "current interfaces. If a file cannot be opened with the access\n" + "requested, @code{open-file} throws an exception.") #define FUNC_NAME s_scm_open_file { SCM port; int fdes; int flags = 0; char *file; - char *mode; + char *md; char *ptr; SCM_VALIDATE_STRING (1, filename); - SCM_VALIDATE_STRING (2, modes); + SCM_VALIDATE_STRING (2, mode); SCM_STRING_COERCE_0TERMINATION_X (filename); - SCM_STRING_COERCE_0TERMINATION_X (modes); + SCM_STRING_COERCE_0TERMINATION_X (mode); file = SCM_STRING_CHARS (filename); - mode = SCM_STRING_CHARS (modes); + md = SCM_STRING_CHARS (mode); - switch (*mode) + switch (*md) { case 'r': flags |= O_RDONLY; @@ -309,9 +310,9 @@ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0, flags |= O_WRONLY | O_CREAT | O_APPEND; break; default: - scm_out_of_range (FUNC_NAME, modes); + scm_out_of_range (FUNC_NAME, mode); } - ptr = mode + 1; + ptr = md + 1; while (*ptr != '\0') { switch (*ptr) @@ -328,7 +329,7 @@ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0, case 'l': /* line buffered: handled during output. */ break; default: - scm_out_of_range (FUNC_NAME, modes); + scm_out_of_range (FUNC_NAME, mode); } ptr++; } @@ -341,7 +342,7 @@ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0, scm_cons (scm_makfrom0str (strerror (en)), scm_cons (filename, SCM_EOL)), en); } - port = scm_fdes_to_port (fdes, mode, filename); + port = scm_fdes_to_port (fdes, md, filename); return port; } #undef FUNC_NAME diff --git a/libguile/gc.c b/libguile/gc.c index 020ee1ce7..972faa5d0 100644 --- a/libguile/gc.c +++ b/libguile/gc.c @@ -151,10 +151,10 @@ scm_assert_cell_valid (SCM cell) SCM_DEFINE (scm_set_debug_cell_accesses_x, "set-debug-cell-accesses!", 1, 0, 0, (SCM flag), - "If FLAG is #f, cell access checking is disabled.\n" - "If FLAG is #t, cell access checking is enabled.\n" - "This procedure only exists because the compile-time flag\n" - "SCM_DEBUG_CELL_ACCESSES was set to 1.\n") + "If @var{flag} is @code{#f}, cell access checking is disabled.\n" + "If @var{flag} is @code{#t}, cell access checking is enabled.\n" + "This procedure only exists when the compile-time flag\n" + "@code{SCM_DEBUG_CELL_ACCESSES} was set to 1.") #define FUNC_NAME s_scm_set_debug_cell_accesses_x { if (SCM_FALSEP (flag)) { @@ -644,9 +644,9 @@ scm_check_freelist (SCM freelist) SCM_DEFINE (scm_gc_set_debug_check_freelist_x, "gc-set-debug-check-freelist!", 1, 0, 0, (SCM flag), - "If FLAG is #t, check the freelist for consistency on each cell allocation.\n" - "This procedure only exists because the GUILE_DEBUG_FREELIST \n" - "compile-time flag was selected.\n") + "If @var{flag} is @code{#t}, check the freelist for consistency\n" + "on each cell allocation. This procedure only exists when the\n" + "@code{GUILE_DEBUG_FREELIST} compile-time flag was selected.") #define FUNC_NAME s_scm_gc_set_debug_check_freelist_x { /* [cmm] I did a double-take when I read this code the first time. @@ -745,7 +745,8 @@ compute_cells_allocated () SCM_DEFINE (scm_gc_stats, "gc-stats", 0, 0, 0, (), - "Returns an association list of statistics about Guile's current use of storage. ") + "Return an association list of statistics about Guile's current\n" + "use of storage.") #define FUNC_NAME s_scm_gc_stats { int i; diff --git a/libguile/hashtab.c b/libguile/hashtab.c index 9bcc16826..50eac4ce8 100644 --- a/libguile/hashtab.c +++ b/libguile/hashtab.c @@ -191,7 +191,7 @@ SCM_DEFINE (scm_hashq_create_handle_x, "hashq-create-handle!", 3, 0, 0, SCM_DEFINE (scm_hashq_ref, "hashq-ref", 2, 1, 0, - (SCM table, SCM obj, SCM dflt), + (SCM table, SCM key, SCM dflt), "Look up @var{key} in the hash table @var{table}, and return the\n" "value (if any) associated with it. If @var{key} is not found,\n" "return @var{default} (or @code{#f} if no @var{default} argument\n" @@ -200,31 +200,32 @@ SCM_DEFINE (scm_hashq_ref, "hashq-ref", 2, 1, 0, { if (SCM_UNBNDP (dflt)) dflt = SCM_BOOL_F; - return scm_hash_fn_ref (table, obj, dflt, scm_ihashq, scm_sloppy_assq, 0); + return scm_hash_fn_ref (table, key, dflt, scm_ihashq, scm_sloppy_assq, 0); } #undef FUNC_NAME SCM_DEFINE (scm_hashq_set_x, "hashq-set!", 3, 0, 0, - (SCM table, SCM obj, SCM val), + (SCM table, SCM key, SCM val), "Find the entry in @var{table} associated with @var{key}, and\n" "store @var{value} there. Uses @code{eq?} for equality testing.") #define FUNC_NAME s_scm_hashq_set_x { - return scm_hash_fn_set_x (table, obj, val, scm_ihashq, scm_sloppy_assq, 0); + return scm_hash_fn_set_x (table, key, val, scm_ihashq, scm_sloppy_assq, 0); } #undef FUNC_NAME SCM_DEFINE (scm_hashq_remove_x, "hashq-remove!", 2, 0, 0, - (SCM table, SCM obj), + (SCM table, SCM key), "Remove @var{key} (and any value associated with it) from\n" "@var{table}. Uses @code{eq?} for equality tests.") #define FUNC_NAME s_scm_hashq_remove_x { - return scm_hash_fn_remove_x (table, obj, scm_ihashq, scm_sloppy_assq, scm_delq_x, 0); + return scm_hash_fn_remove_x (table, key, scm_ihashq, scm_sloppy_assq, + scm_delq_x, 0); } #undef FUNC_NAME @@ -251,13 +252,14 @@ SCM_DEFINE (scm_hashv_create_handle_x, "hashv-create-handle!", 3, 0, 0, "associates @var{key} with @var{init}.") #define FUNC_NAME s_scm_hashv_create_handle_x { - return scm_hash_fn_create_handle_x (table, key, init, scm_ihashv, scm_sloppy_assv, 0); + return scm_hash_fn_create_handle_x (table, key, init, scm_ihashv, + scm_sloppy_assv, 0); } #undef FUNC_NAME SCM_DEFINE (scm_hashv_ref, "hashv-ref", 2, 1, 0, - (SCM table, SCM obj, SCM dflt), + (SCM table, SCM key, SCM dflt), "Look up @var{key} in the hash table @var{table}, and return the\n" "value (if any) associated with it. If @var{key} is not found,\n" "return @var{default} (or @code{#f} if no @var{default} argument\n" @@ -266,30 +268,31 @@ SCM_DEFINE (scm_hashv_ref, "hashv-ref", 2, 1, 0, { if (SCM_UNBNDP (dflt)) dflt = SCM_BOOL_F; - return scm_hash_fn_ref (table, obj, dflt, scm_ihashv, scm_sloppy_assv, 0); + return scm_hash_fn_ref (table, key, dflt, scm_ihashv, scm_sloppy_assv, 0); } #undef FUNC_NAME SCM_DEFINE (scm_hashv_set_x, "hashv-set!", 3, 0, 0, - (SCM table, SCM obj, SCM val), + (SCM table, SCM key, SCM val), "Find the entry in @var{table} associated with @var{key}, and\n" "store @var{value} there. Uses @code{eqv?} for equality testing.") #define FUNC_NAME s_scm_hashv_set_x { - return scm_hash_fn_set_x (table, obj, val, scm_ihashv, scm_sloppy_assv, 0); + return scm_hash_fn_set_x (table, key, val, scm_ihashv, scm_sloppy_assv, 0); } #undef FUNC_NAME SCM_DEFINE (scm_hashv_remove_x, "hashv-remove!", 2, 0, 0, - (SCM table, SCM obj), + (SCM table, SCM key), "Remove @var{key} (and any value associated with it) from\n" "@var{table}. Uses @code{eqv?} for equality tests.") #define FUNC_NAME s_scm_hashv_remove_x { - return scm_hash_fn_remove_x (table, obj, scm_ihashv, scm_sloppy_assv, scm_delv_x, 0); + return scm_hash_fn_remove_x (table, key, scm_ihashv, scm_sloppy_assv, + scm_delv_x, 0); } #undef FUNC_NAME @@ -321,7 +324,7 @@ SCM_DEFINE (scm_hash_create_handle_x, "hash-create-handle!", 3, 0, 0, SCM_DEFINE (scm_hash_ref, "hash-ref", 2, 1, 0, - (SCM table, SCM obj, SCM dflt), + (SCM table, SCM key, SCM dflt), "Look up @var{key} in the hash table @var{table}, and return the\n" "value (if any) associated with it. If @var{key} is not found,\n" "return @var{default} (or @code{#f} if no @var{default} argument\n" @@ -330,32 +333,33 @@ SCM_DEFINE (scm_hash_ref, "hash-ref", 2, 1, 0, { if (SCM_UNBNDP (dflt)) dflt = SCM_BOOL_F; - return scm_hash_fn_ref (table, obj, dflt, scm_ihash, scm_sloppy_assoc, 0); + return scm_hash_fn_ref (table, key, dflt, scm_ihash, scm_sloppy_assoc, 0); } #undef FUNC_NAME SCM_DEFINE (scm_hash_set_x, "hash-set!", 3, 0, 0, - (SCM table, SCM obj, SCM val), + (SCM table, SCM key, SCM val), "Find the entry in @var{table} associated with @var{key}, and\n" "store @var{value} there. Uses @code{equal?} for equality\n" "testing.") #define FUNC_NAME s_scm_hash_set_x { - return scm_hash_fn_set_x (table, obj, val, scm_ihash, scm_sloppy_assoc, 0); + return scm_hash_fn_set_x (table, key, val, scm_ihash, scm_sloppy_assoc, 0); } #undef FUNC_NAME SCM_DEFINE (scm_hash_remove_x, "hash-remove!", 2, 0, 0, - (SCM table, SCM obj), + (SCM table, SCM key), "Remove @var{key} (and any value associated with it) from\n" "@var{table}. Uses @code{equal?} for equality tests.") #define FUNC_NAME s_scm_hash_remove_x { - return scm_hash_fn_remove_x (table, obj, scm_ihash, scm_sloppy_assoc, scm_delete_x, 0); + return scm_hash_fn_remove_x (table, key, scm_ihash, scm_sloppy_assoc, + scm_delete_x, 0); } #undef FUNC_NAME @@ -415,11 +419,11 @@ scm_delx_x (SCM obj,SCM alist,struct scm_ihashx_closure * closure) SCM_DEFINE (scm_hashx_get_handle, "hashx-get-handle", 4, 0, 0, - (SCM hash, SCM assoc, SCM table, SCM obj), - "This behaves the same way as the corresponding @code{-get-handle}\n" - "function, but uses @var{hasher} as a\n" - "hash function and @var{assoc} to compare keys. @code{hasher} must\n" - "be a function that takes two arguments, a key to be hashed and a\n" + (SCM hash, SCM assoc, SCM table, SCM key), + "This behaves the same way as the corresponding\n" + "@code{-get-handle} function, but uses @var{hash} as a hash\n" + "function and @var{assoc} to compare keys. @code{hash} must be\n" + "a function that takes two arguments, a key to be hashed and a\n" "table size. @code{assoc} must be an associator function, like\n" "@code{assoc}, @code{assq} or @code{assv}.") #define FUNC_NAME s_scm_hashx_get_handle @@ -427,17 +431,18 @@ SCM_DEFINE (scm_hashx_get_handle, "hashx-get-handle", 4, 0, 0, struct scm_ihashx_closure closure; closure.hash = hash; closure.assoc = assoc; - return scm_hash_fn_get_handle (table, obj, scm_ihashx, scm_sloppy_assx, (void *)&closure); + return scm_hash_fn_get_handle (table, key, scm_ihashx, scm_sloppy_assx, + (void *)&closure); } #undef FUNC_NAME SCM_DEFINE (scm_hashx_create_handle_x, "hashx-create-handle!", 5, 0, 0, - (SCM hash, SCM assoc, SCM table, SCM obj, SCM init), - "This behaves the same way as the corresponding @code{-create-handle}\n" - "function, but uses @var{hasher} as a\n" - "hash function and @var{assoc} to compare keys. @code{hasher} must\n" - "be a function that takes two arguments, a key to be hashed and a\n" + (SCM hash, SCM assoc, SCM table, SCM key, SCM init), + "This behaves the same way as the corresponding\n" + "@code{-create-handle} function, but uses @var{hash} as a hash\n" + "function and @var{assoc} to compare keys. @code{hash} must be\n" + "a function that takes two arguments, a key to be hashed and a\n" "table size. @code{assoc} must be an associator function, like\n" "@code{assoc}, @code{assq} or @code{assv}.") #define FUNC_NAME s_scm_hashx_create_handle_x @@ -445,22 +450,24 @@ SCM_DEFINE (scm_hashx_create_handle_x, "hashx-create-handle!", 5, 0, 0, struct scm_ihashx_closure closure; closure.hash = hash; closure.assoc = assoc; - return scm_hash_fn_create_handle_x (table, obj, init, scm_ihashx, scm_sloppy_assx, (void *)&closure); + return scm_hash_fn_create_handle_x (table, key, init, scm_ihashx, + scm_sloppy_assx, (void *)&closure); } #undef FUNC_NAME SCM_DEFINE (scm_hashx_ref, "hashx-ref", 4, 1, 0, - (SCM hash, SCM assoc, SCM table, SCM obj, SCM dflt), + (SCM hash, SCM assoc, SCM table, SCM key, SCM dflt), "This behaves the same way as the corresponding @code{ref}\n" - "function, but uses @var{hasher} as a\n" - "hash function and @var{assoc} to compare keys. @code{hasher} must\n" - "be a function that takes two arguments, a key to be hashed and a\n" - "table size. @code{assoc} must be an associator function, like\n" - "@code{assoc}, @code{assq} or @code{assv}.\n\n" - "By way of illustration, @code{hashq-ref table key} is equivalent\n" - "to @code{hashx-ref hashq assq table key}.") + "function, but uses @var{hash} as a hash function and\n" + "@var{assoc} to compare keys. @code{hash} must be a function\n" + "that takes two arguments, a key to be hashed and a table size.\n" + "@code{assoc} must be an associator function, like @code{assoc},\n" + "@code{assq} or @code{assv}.\n" + "\n" + "By way of illustration, @code{hashq-ref table key} is\n" + "equivalent to @code{hashx-ref hashq assq table key}.") #define FUNC_NAME s_scm_hashx_ref { struct scm_ihashx_closure closure; @@ -468,7 +475,8 @@ SCM_DEFINE (scm_hashx_ref, "hashx-ref", 4, 1, 0, dflt = SCM_BOOL_F; closure.hash = hash; closure.assoc = assoc; - return scm_hash_fn_ref (table, obj, dflt, scm_ihashx, scm_sloppy_assx, (void *)&closure); + return scm_hash_fn_ref (table, key, dflt, scm_ihashx, scm_sloppy_assx, + (void *)&closure); } #undef FUNC_NAME @@ -476,21 +484,23 @@ SCM_DEFINE (scm_hashx_ref, "hashx-ref", 4, 1, 0, SCM_DEFINE (scm_hashx_set_x, "hashx-set!", 5, 0, 0, - (SCM hash, SCM assoc, SCM table, SCM obj, SCM val), + (SCM hash, SCM assoc, SCM table, SCM key, SCM val), "This behaves the same way as the corresponding @code{set!}\n" - "function, but uses @var{hasher} as a\n" - "hash function and @var{assoc} to compare keys. @code{hasher} must\n" - "be a function that takes two arguments, a key to be hashed and a\n" - "table size. @code{assoc} must be an associator function, like\n" - "@code{assoc}, @code{assq} or @code{assv}.\n\n" - "By way of illustration, @code{hashq-set! table key} is equivalent\n" - "to @code{hashx-set! hashq assq table key}.") + "function, but uses @var{hash} as a hash function and\n" + "@var{assoc} to compare keys. @code{hash} must be a function\n" + "that takes two arguments, a key to be hashed and a table size.\n" + "@code{assoc} must be an associator function, like @code{assoc},\n" + "@code{assq} or @code{assv}.\n" + "\n" + " By way of illustration, @code{hashq-set! table key} is\n" + "equivalent to @code{hashx-set! hashq assq table key}.") #define FUNC_NAME s_scm_hashx_set_x { struct scm_ihashx_closure closure; closure.hash = hash; closure.assoc = assoc; - return scm_hash_fn_set_x (table, obj, val, scm_ihashx, scm_sloppy_assx, (void *)&closure); + return scm_hash_fn_set_x (table, key, val, scm_ihashx, scm_sloppy_assx, + (void *)&closure); } #undef FUNC_NAME diff --git a/libguile/ioext.c b/libguile/ioext.c index 31f874c58..c69be4d42 100644 --- a/libguile/ioext.c +++ b/libguile/ioext.c @@ -165,15 +165,16 @@ SCM_DEFINE (scm_read_string_x_partial, "read-string!/partial", 1, 3, 0, #undef FUNC_NAME SCM_DEFINE (scm_ftell, "ftell", 1, 0, 0, - (SCM object), - "Returns an integer representing the current position of @var{fd/port},\n" - "measured from the beginning. Equivalent to:\n" - "@smalllisp\n" + (SCM fd_port), + "Return an integer representing the current position of\n" + "@var{fd/port}, measured from the beginning. Equivalent to:\n" + "\n" + "@lisp\n" "(seek port 0 SEEK_CUR)\n" - "@end smalllisp") + "@end lisp") #define FUNC_NAME s_scm_ftell { - return scm_seek (object, SCM_INUM0, SCM_MAKINUM (SEEK_CUR)); + return scm_seek (fd_port, SCM_INUM0, SCM_MAKINUM (SEEK_CUR)); } #undef FUNC_NAME @@ -181,12 +182,12 @@ SCM_DEFINE (scm_ftell, "ftell", 1, 0, 0, #if (SCM_DEBUG_DEPRECATED == 0) SCM_DEFINE (scm_fseek, "fseek", 3, 0, 0, - (SCM object, SCM offset, SCM whence), - "Obsolete. Almost the same as seek, above, but the return value is\n" - "unspecified.") + (SCM fd_port, SCM offset, SCM whence), + "Obsolete. Almost the same as @code{seek}, but the return value\n" + "is unspecified.") #define FUNC_NAME s_scm_fseek { - scm_seek (object, offset, whence); + scm_seek (fd_port, offset, whence); return SCM_UNSPECIFIED; } #undef FUNC_NAME @@ -242,7 +243,9 @@ SCM_DEFINE (scm_redirect_port, "redirect-port", 2, 0, 0, SCM_DEFINE (scm_dup_to_fdes, "dup->fdes", 1, 1, 0, (SCM fd_or_port, SCM fd), - "Returns an integer file descriptor.") + "Return a new integer file descriptor referring to the open file\n" + "designated by @var{fd_or_port}, which must be either an open\n" + "file port or a file descriptor.") #define FUNC_NAME s_scm_dup_to_fdes { int oldfd, newfd, rv; @@ -307,8 +310,8 @@ SCM_DEFINE (scm_dup2, "dup2", 2, 0, 0, SCM_DEFINE (scm_fileno, "fileno", 1, 0, 0, (SCM port), - "Returns the integer file descriptor underlying @var{port}.\n" - "Does not change its revealed count.") + "Return the integer file descriptor underlying @var{port}. Does\n" + "not change its revealed count.") #define FUNC_NAME s_scm_fileno { port = SCM_COERCE_OUTPORT (port); @@ -323,8 +326,8 @@ SCM_DEFINE (scm_fileno, "fileno", 1, 0, 0, if it is not going to assume that the arg is a port */ SCM_DEFINE (scm_isatty_p, "isatty?", 1, 0, 0, (SCM port), - "Returns @code{#t} if @var{port} is using a serial\n" - "non-file device, otherwise @code{#f}.") + "Return @code{#t} if @var{port} is using a serial non--file\n" + "device, otherwise @code{#f}.") #define FUNC_NAME s_scm_isatty_p { int rv; @@ -343,10 +346,10 @@ SCM_DEFINE (scm_isatty_p, "isatty?", 1, 0, 0, SCM_DEFINE (scm_fdopen, "fdopen", 2, 0, 0, (SCM fdes, SCM modes), - "Returns a new port based on the file descriptor @var{fdes}.\n" - "Modes are given by the string @var{modes}. The revealed count of the port\n" - "is initialized to zero. The modes string is the same as that accepted\n" - "by @ref{File Ports, open-file}.") + "Return a new port based on the file descriptor @var{fdes}.\n" + "Modes are given by the string @var{modes}. The revealed count\n" + "of the port is initialized to zero. The modes string is the\n" + "same as that accepted by @ref{File Ports, open-file}.") #define FUNC_NAME s_scm_fdopen { SCM_VALIDATE_INUM (1,fdes); @@ -403,8 +406,9 @@ SCM_DEFINE (scm_primitive_move_to_fdes, "primitive-move->fdes", 2, 0, 0, /* Return a list of ports using a given file descriptor. */ SCM_DEFINE (scm_fdes_to_ports, "fdes->ports", 1, 0, 0, (SCM fd), - "Returns a list of existing ports which have @var{fdes} as an\n" - "underlying file descriptor, without changing their revealed counts.") + "Return a list of existing ports which have @var{fdes} as an\n" + "underlying file descriptor, without changing their revealed\n" + "counts.") #define FUNC_NAME s_scm_fdes_to_ports { SCM result = SCM_EOL; diff --git a/libguile/keywords.c b/libguile/keywords.c index 3509314ea..ff86b582f 100644 --- a/libguile/keywords.c +++ b/libguile/keywords.c @@ -109,7 +109,8 @@ scm_c_make_keyword (char *s) SCM_DEFINE (scm_keyword_p, "keyword?", 1, 0, 0, (SCM obj), - "Returns @code{#t} if the argument @var{obj} is a keyword, else @code{#f}.") + "Return @code{#t} if the argument @var{obj} is a keyword, else\n" + "@code{#f}.") #define FUNC_NAME s_scm_keyword_p { return SCM_BOOL (SCM_KEYWORDP (obj)); diff --git a/libguile/list.c b/libguile/list.c index d5b486bdf..bf1a1725c 100644 --- a/libguile/list.c +++ b/libguile/list.c @@ -194,19 +194,19 @@ SCM_DEFINE (scm_append, "append", 0, 0, 1, (SCM args), "Return a list consisting of the elements the lists passed as\n" "arguments.\n" - "@example\n" + "@lisp\n" "(append '(x) '(y)) @result{} (x y)\n" "(append '(a) '(b c d)) @result{} (a b c d)\n" "(append '(a (b)) '((c))) @result{} (a (b) (c))\n" - "@end example\n" + "@end lisp\n" "The resulting list is always newly allocated, except that it\n" "shares structure with the last list argument. The last\n" "argument may actually be any object; an improper list results\n" "if the last argument is not a proper list.\n" - "@example\n" + "@lisp\n" "(append '(a b) '(c . d)) @result{} (a b c . d)\n" "(append '() 'a) @result{} a\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_append { SCM_VALIDATE_REST_ARGUMENT (args); @@ -235,25 +235,26 @@ SCM_DEFINE (scm_append, "append", 0, 0, 1, SCM_DEFINE (scm_append_x, "append!", 0, 0, 1, - (SCM args), - "A destructive version of @code{append} (@pxref{Pairs and Lists,,,r4rs,\n" - "The Revised^4 Report on Scheme}). The cdr field of each list's final\n" - "pair is changed to point to the head of the next list, so no consing is\n" - "performed. Return a pointer to the mutated list.") + (SCM lists), + "A destructive version of @code{append} (@pxref{Pairs and\n" + "Lists,,,r4rs, The Revised^4 Report on Scheme}). The cdr field\n" + "of each list's final pair is changed to point to the head of\n" + "the next list, so no consing is performed. Return a pointer to\n" + "the mutated list.") #define FUNC_NAME s_scm_append_x { - SCM_VALIDATE_REST_ARGUMENT (args); + SCM_VALIDATE_REST_ARGUMENT (lists); while (1) { - if (SCM_NULLP (args)) { + if (SCM_NULLP (lists)) { return SCM_EOL; } else { - SCM arg = SCM_CAR (args); - args = SCM_CDR (args); - if (SCM_NULLP (args)) { + SCM arg = SCM_CAR (lists); + lists = SCM_CDR (lists); + if (SCM_NULLP (lists)) { return arg; } else if (!SCM_NULLP (arg)) { SCM_VALIDATE_CONS (SCM_ARG1, arg); - SCM_SETCDR (scm_last_pair (arg), scm_append_x (args)); + SCM_SETCDR (scm_last_pair (arg), scm_append_x (lists)); return arg; } } @@ -565,7 +566,7 @@ SCM_DEFINE (scm_sloppy_member, "sloppy-member", 2, 0, 0, /* The function scm_c_memq returns the first sublist of list whose car is * 'eq?' obj, where the sublists of list are the non-empty lists returned by * (list-tail list k) for k less than the length of list. If obj does not - * occur in list, then #f (not the empty list) is returned. (r5rs) + * occur in list, then #f (not the empty list) is returned. * List must be a proper list, otherwise scm_c_memq may crash or loop * endlessly. */ diff --git a/libguile/macros.c b/libguile/macros.c index 1d5aadd18..44eac33d8 100644 --- a/libguile/macros.c +++ b/libguile/macros.c @@ -55,9 +55,10 @@ scm_bits_t scm_tc16_macro; SCM_DEFINE (scm_makacro, "procedure->syntax", 1, 0, 0, (SCM code), - "Returns a @dfn{macro} which, when a symbol defined to this value\n" - "appears as the first symbol in an expression, returns the result\n" - "of applying @var{code} to the expression and the environment.") + "Return a @dfn{macro} which, when a symbol defined to this value\n" + "appears as the first symbol in an expression, returns the\n" + "result of applying @var{code} to the expression and the\n" + "environment.") #define FUNC_NAME s_scm_makacro { SCM_VALIDATE_PROC (1,code); @@ -68,18 +69,19 @@ SCM_DEFINE (scm_makacro, "procedure->syntax", 1, 0, 0, SCM_DEFINE (scm_makmacro, "procedure->macro", 1, 0, 0, (SCM code), - "Returns a @dfn{macro} which, when a symbol defined to this value\n" - "appears as the first symbol in an expression, evaluates the result\n" - "of applying @var{code} to the expression and the environment.\n" - "The value returned from @var{code} which has been passed to\n" - "@code{procedure->memoizing-macro} replaces the form passed to\n" - "@var{code}. For example:\n\n" - "@example\n" + "Return a @dfn{macro} which, when a symbol defined to this value\n" + "appears as the first symbol in an expression, evaluates the\n" + "result of applying @var{code} to the expression and the\n" + "environment. The value returned from @var{code} which has been\n" + "passed to @code{procedure->memoizing-macro} replaces the form\n" + "passed to @var{code}. For example:\n" + "\n" + "@lisp\n" "(define trace\n" " (procedure->macro\n" " (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))\n\n" "(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_makmacro { SCM_VALIDATE_PROC (1,code); @@ -90,18 +92,19 @@ SCM_DEFINE (scm_makmacro, "procedure->macro", 1, 0, 0, SCM_DEFINE (scm_makmmacro, "procedure->memoizing-macro", 1, 0, 0, (SCM code), - "Returns a @dfn{macro} which, when a symbol defined to this value\n" - "appears as the first symbol in an expression, evaluates the result\n" - "of applying @var{proc} to the expression and the environment.\n" - "The value returned from @var{proc} which has been passed to\n" - "@code{procedure->memoizing-macro} replaces the form passed to\n" - "@var{proc}. For example:\n\n" - "@example\n" - "(define trace\n" - " (procedure->macro\n" - " (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))\n\n" - "(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).\n" - "@end example") + "Return a @dfn{macro} which, when a symbol defined to this value\n" + "appears as the first symbol in an expression, evaluates the\n" + "result of applying @var{proc} to the expression and the\n" + "environment. The value returned from @var{proc} which has been\n" + "passed to @code{procedure->memoizing-macro} replaces the form\n" + "passed to @var{proc}. For example:\n" + "\n" + "@lisp\n" + "(define trace\n" + " (procedure->macro\n" + " (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))\n\n" + "(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).\n" + "@end lisp") #define FUNC_NAME s_scm_makmmacro { SCM_VALIDATE_PROC (1,code); @@ -127,10 +130,11 @@ SCM_SYMBOL (scm_sym_mmacro, "macro!"); SCM_DEFINE (scm_macro_type, "macro-type", 1, 0, 0, (SCM m), - "Return one of the symbols @code{syntax}, @code{macro} or @code{macro!},\n" - "depending on whether @var{obj} is a syntax tranformer, a regular macro,\n" - "or a memoizing macro, respectively. If @var{obj} is not a macro,\n" - "@code{#f} is returned.") + "Return one of the symbols @code{syntax}, @code{macro} or\n" + "@code{macro!}, depending on whether @var{m} is a syntax\n" + "tranformer, a regular macro, or a memoizing macro,\n" + "respectively. If @var{m} is not a macro, @code{#f} is\n" + "returned.") #define FUNC_NAME s_scm_macro_type { if (!SCM_TYP16_PREDICATE (scm_tc16_macro, m)) diff --git a/libguile/modules.c b/libguile/modules.c index 8e2edb1e3..4259b05f0 100644 --- a/libguile/modules.c +++ b/libguile/modules.c @@ -95,11 +95,11 @@ scm_set_current_module (SCM module) SCM_DEFINE (scm_interaction_environment, "interaction-environment", 0, 0, 0, (), - "This procedure returns a specifier for the environment that contains\n" - "implementation-defined bindings, typically a superset of those listed in\n" - "the report. The intent is that this procedure will return the\n" - "environment in which the implementation would evaluate expressions\n" - "dynamically typed by the user.") + "Return a specifier for the environment that contains\n" + "implementation--defined bindings, typically a superset of those\n" + "listed in the report. The intent is that this procedure will\n" + "return the environment in which the implementation would\n" + "evaluate expressions dynamically typed by the user.") #define FUNC_NAME s_scm_interaction_environment { return scm_current_module (); diff --git a/libguile/net_db.c b/libguile/net_db.c index 27721ffc0..2ef227f48 100644 --- a/libguile/net_db.c +++ b/libguile/net_db.c @@ -89,11 +89,11 @@ extern int h_errno; SCM_DEFINE (scm_inet_aton, "inet-aton", 1, 0, 0, (SCM address), - "Converts a string containing an Internet host address in the traditional\n" - "dotted decimal notation into an integer.\n\n" - "@smalllisp\n" - "(inet-aton \"127.0.0.1\") @result{} 2130706433\n\n" - "@end smalllisp") + "Converts a string containing an Internet host address in the\n" + "traditional dotted decimal notation into an integer.\n" + "@lisp\n" + "(inet-aton \"127.0.0.1\") @result{} 2130706433\n" + "@end lisp") #define FUNC_NAME s_scm_inet_aton { struct in_addr soka; @@ -109,11 +109,11 @@ SCM_DEFINE (scm_inet_aton, "inet-aton", 1, 0, 0, SCM_DEFINE (scm_inet_ntoa, "inet-ntoa", 1, 0, 0, (SCM inetid), - "Converts an integer Internet host address into a string with the\n" - "traditional dotted decimal representation.\n\n" - "@smalllisp\n" + "Converts an integer Internet host address into a string with\n" + "the traditional dotted decimal representation.\n" + "@lisp\n" "(inet-ntoa 2130706433) @result{} \"127.0.0.1\"\n" - "@end smalllisp") + "@end lisp") #define FUNC_NAME s_scm_inet_ntoa { struct in_addr addr; @@ -129,10 +129,11 @@ SCM_DEFINE (scm_inet_ntoa, "inet-ntoa", 1, 0, 0, #ifdef HAVE_INET_NETOF SCM_DEFINE (scm_inet_netof, "inet-netof", 1, 0, 0, (SCM address), - "Returns the network number part of the given integer Internet address.\n\n" - "@smalllisp\n" + "Return the network number part of the given integer Internet\n" + "address.\n" + "@lisp\n" "(inet-netof 2130706433) @result{} 127\n" - "@end smalllisp") + "@end lisp") #define FUNC_NAME s_scm_inet_netof { struct in_addr addr; @@ -145,11 +146,11 @@ SCM_DEFINE (scm_inet_netof, "inet-netof", 1, 0, 0, #ifdef HAVE_INET_LNAOF SCM_DEFINE (scm_lnaof, "inet-lnaof", 1, 0, 0, (SCM address), - "Returns the local-address-with-network part of the given Internet\n" - "address.\n\n" - "@smalllisp\n" + "Return the local-address-with-network part of the given\n" + "Internet address.\n" + "@lisp\n" "(inet-lnaof 2130706433) @result{} 1\n" - "@end smalllisp") + "@end lisp") #define FUNC_NAME s_scm_lnaof { struct in_addr addr; @@ -162,11 +163,12 @@ SCM_DEFINE (scm_lnaof, "inet-lnaof", 1, 0, 0, #ifdef HAVE_INET_MAKEADDR SCM_DEFINE (scm_inet_makeaddr, "inet-makeaddr", 2, 0, 0, (SCM net, SCM lna), - "Makes an Internet host address by combining the network number @var{net}\n" - "with the local-address-within-network number @var{lna}.\n\n" - "@smalllisp\n" + "Makes an Internet host address by combining the network number\n" + "@var{net} with the local-address-within-network number\n" + "@var{lna}.\n" + "@lisp\n" "(inet-makeaddr 127 1) @result{} 2130706433\n" - "@end smalllisp") + "@end lisp") #define FUNC_NAME s_scm_inet_makeaddr { struct in_addr addr; diff --git a/libguile/numbers.c b/libguile/numbers.c index 17fa9fda1..c712b6544 100644 --- a/libguile/numbers.c +++ b/libguile/numbers.c @@ -746,13 +746,13 @@ SCM scm_big_test(SCM_BIGDIG *x, scm_sizet nx, int xsgn, SCM bigy) SCM_DEFINE1 (scm_logand, "logand", scm_tc7_asubr, (SCM n1, SCM n2), - "Returns the integer which is the bit-wise AND of the two integer\n" - "arguments.\n\n" - "Example:\n" - "@lisp\n" - "(number->string (logand #b1100 #b1010) 2)\n" - " @result{} \"1000\"\n" - "@end lisp") + "Return the integer which is the bit-wise AND of the two integer\n" + "arguments.\n" + "\n" + "@lisp\n" + "(number->string (logand #b1100 #b1010) 2)\n" + " @result{} \"1000\"\n" + "@end lisp") #define FUNC_NAME s_scm_logand { long int nn1; @@ -833,13 +833,13 @@ SCM_DEFINE1 (scm_logand, "logand", scm_tc7_asubr, SCM_DEFINE1 (scm_logior, "logior", scm_tc7_asubr, (SCM n1, SCM n2), - "Returns the integer which is the bit-wise OR of the two integer\n" - "arguments.\n\n" - "Example:\n" - "@lisp\n" - "(number->string (logior #b1100 #b1010) 2)\n" - " @result{} \"1110\"\n" - "@end lisp") + "Return the integer which is the bit-wise OR of the two integer\n" + "arguments.\n" + "\n" + "@lisp\n" + "(number->string (logior #b1100 #b1010) 2)\n" + " @result{} \"1110\"\n" + "@end lisp") #define FUNC_NAME s_scm_logior { long int nn1; @@ -919,13 +919,13 @@ SCM_DEFINE1 (scm_logior, "logior", scm_tc7_asubr, SCM_DEFINE1 (scm_logxor, "logxor", scm_tc7_asubr, (SCM n1, SCM n2), - "Returns the integer which is the bit-wise XOR of the two integer\n" - "arguments.\n\n" - "Example:\n" - "@lisp\n" - "(number->string (logxor #b1100 #b1010) 2)\n" - " @result{} \"110\"\n" - "@end lisp") + "Return the integer which is the bit-wise XOR of the two integer\n" + "arguments.\n" + "\n" + "@lisp\n" + "(number->string (logxor #b1100 #b1010) 2)\n" + " @result{} \"110\"\n" + "@end lisp") #define FUNC_NAME s_scm_logxor { long int nn1; @@ -989,54 +989,54 @@ SCM_DEFINE1 (scm_logxor, "logxor", scm_tc7_asubr, SCM_DEFINE (scm_logtest, "logtest", 2, 0, 0, - (SCM n1, SCM n2), - "@example\n" + (SCM j, SCM k), + "@lisp\n" "(logtest j k) @equiv{} (not (zero? (logand j k)))\n\n" "(logtest #b0100 #b1011) @result{} #f\n" "(logtest #b0100 #b0111) @result{} #t\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_logtest { - long int nn1; + long int nj; - if (SCM_INUMP (n1)) { - nn1 = SCM_INUM (n1); - if (SCM_INUMP (n2)) { - long nn2 = SCM_INUM (n2); - return SCM_BOOL (nn1 & nn2); - } else if (SCM_BIGP (n2)) { + if (SCM_INUMP (j)) { + nj = SCM_INUM (j); + if (SCM_INUMP (k)) { + long nk = SCM_INUM (k); + return SCM_BOOL (nj & nk); + } else if (SCM_BIGP (k)) { intbig: { # ifndef SCM_DIGSTOOBIG - long z = scm_pseudolong (nn1); + long z = scm_pseudolong (nj); return scm_big_test ((SCM_BIGDIG *)&z, SCM_DIGSPERLONG, - (nn1 < 0) ? SCM_BIGSIGNFLAG : 0, n2); + (nj < 0) ? SCM_BIGSIGNFLAG : 0, k); # else SCM_BIGDIG zdigs [SCM_DIGSPERLONG]; - scm_longdigs (nn1, zdigs); + scm_longdigs (nj, zdigs); return scm_big_test (zdigs, SCM_DIGSPERLONG, - (nn1 < 0) ? SCM_BIGSIGNFLAG : 0, n2); + (nj < 0) ? SCM_BIGSIGNFLAG : 0, k); # endif } } else { - SCM_WRONG_TYPE_ARG (SCM_ARG2, n2); + SCM_WRONG_TYPE_ARG (SCM_ARG2, k); } - } else if (SCM_BIGP (n1)) { - if (SCM_INUMP (n2)) { - SCM_SWAP (n1, n2); - nn1 = SCM_INUM (n1); + } else if (SCM_BIGP (j)) { + if (SCM_INUMP (k)) { + SCM_SWAP (j, k); + nj = SCM_INUM (j); goto intbig; - } else if (SCM_BIGP (n2)) { - if (SCM_NUMDIGS (n1) > SCM_NUMDIGS (n2)) { - SCM_SWAP (n1, n2); + } else if (SCM_BIGP (k)) { + if (SCM_NUMDIGS (j) > SCM_NUMDIGS (k)) { + SCM_SWAP (j, k); } - return scm_big_test (SCM_BDIGITS (n1), SCM_NUMDIGS (n1), - SCM_BIGSIGN (n1), n2); + return scm_big_test (SCM_BDIGITS (j), SCM_NUMDIGS (j), + SCM_BIGSIGN (j), k); } else { - SCM_WRONG_TYPE_ARG (SCM_ARG2, n2); + SCM_WRONG_TYPE_ARG (SCM_ARG2, k); } } else { - SCM_WRONG_TYPE_ARG (SCM_ARG1, n1); + SCM_WRONG_TYPE_ARG (SCM_ARG1, j); } } #undef FUNC_NAME @@ -1044,14 +1044,14 @@ SCM_DEFINE (scm_logtest, "logtest", 2, 0, 0, SCM_DEFINE (scm_logbit_p, "logbit?", 2, 0, 0, (SCM index, SCM j), - "@example\n" + "@lisp\n" "(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)\n\n" "(logbit? 0 #b1101) @result{} #t\n" "(logbit? 1 #b1101) @result{} #f\n" "(logbit? 2 #b1101) @result{} #t\n" "(logbit? 3 #b1101) @result{} #t\n" "(logbit? 4 #b1101) @result{} #f\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_logbit_p { unsigned long int iindex; @@ -1092,14 +1092,15 @@ SCM_DEFINE (scm_logbit_p, "logbit?", 2, 0, 0, SCM_DEFINE (scm_lognot, "lognot", 1, 0, 0, (SCM n), - "Returns the integer which is the 2s-complement of the integer argument.\n\n" - "Example:\n" + "Return the integer which is the 2s-complement of the integer\n" + "argument.\n" + "\n" "@lisp\n" "(number->string (lognot #b10000000) 2)\n" " @result{} \"-10000001\"\n" "(number->string (lognot #b0) 2)\n" " @result{} \"-1\"\n" - "@end lisp\n") + "@end lisp") #define FUNC_NAME s_scm_lognot { return scm_difference (SCM_MAKINUM (-1L), n); @@ -1108,8 +1109,9 @@ SCM_DEFINE (scm_lognot, "lognot", 1, 0, 0, SCM_DEFINE (scm_integer_expt, "integer-expt", 2, 0, 0, (SCM n, SCM k), - "Returns @var{n} raised to the non-negative integer exponent @var{k}.\n\n" - "Example:\n" + "Return @var{n} raised to the non-negative integer exponent\n" + "@var{k}.\n" + "\n" "@lisp\n" "(integer-expt 2 5)\n" " @result{} 32\n" @@ -1148,21 +1150,20 @@ SCM_DEFINE (scm_integer_expt, "integer-expt", 2, 0, 0, SCM_DEFINE (scm_ash, "ash", 2, 0, 0, (SCM n, SCM cnt), - "The function ash performs an arithmetic shift left by @var{CNT}\n" - "bits (or shift right, if @var{cnt} is negative).\n" - "'Arithmetic' means, that the function does not guarantee to\n" - "keep the bit structure of @var{n}, but rather guarantees that\n" - "the result will always be rounded towards minus infinity.\n" - "Therefore, the results of ash and a corresponding bitwise\n" - "shift will differ if N is negative.\n\n" + "The function ash performs an arithmetic shift left by @var{cnt}\n" + "bits (or shift right, if @var{cnt} is negative). 'Arithmetic'\n" + "means, that the function does not guarantee to keep the bit\n" + "structure of @var{n}, but rather guarantees that the result\n" + "will always be rounded towards minus infinity. Therefore, the\n" + "results of ash and a corresponding bitwise shift will differ if\n" + "@var{n} is negative.\n" + "\n" "Formally, the function returns an integer equivalent to\n" - "@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.\n\n" - "Example:\n" + "@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.\n" + "\n" "@lisp\n" - "(number->string (ash #b1 3) 2)\n" - " @result{} \"1000\"\n" - "(number->string (ash #b1010 -1) 2)\n" - " @result{} \"101\"\n" + "(number->string (ash #b1 3) 2) @result{} \"1000\"\n" + "(number->string (ash #b1010 -1) 2) @result{} \"101\"\n" "@end lisp") #define FUNC_NAME s_scm_ash { @@ -1207,10 +1208,10 @@ SCM_DEFINE (scm_ash, "ash", 2, 0, 0, SCM_DEFINE (scm_bit_extract, "bit-extract", 3, 0, 0, (SCM n, SCM start, SCM end), - "Returns the integer composed of the @var{start} (inclusive) through\n" - "@var{end} (exclusive) bits of @var{n}. The @var{start}th bit becomes\n" - "the 0-th bit in the result.@refill\n\n" - "Example:\n" + "Return the integer composed of the @var{start} (inclusive)\n" + "through @var{end} (exclusive) bits of @var{n}. The\n" + "@var{start}th bit becomes the 0-th bit in the result.\n" + "\n" "@lisp\n" "(number->string (bit-extract #b1101101010 0 4) 2)\n" " @result{} \"1010\"\n" @@ -1276,11 +1277,11 @@ static const char scm_logtab[] = { SCM_DEFINE (scm_logcount, "logcount", 1, 0, 0, (SCM n), - "Returns the number of bits in integer @var{n}. If integer is positive,\n" - "the 1-bits in its binary representation are counted. If negative, the\n" - "0-bits in its two's-complement binary representation are counted. If 0,\n" - "0 is returned.\n\n" - "Example:\n" + "Return the number of bits in integer @var{n}. If integer is\n" + "positive, the 1-bits in its binary representation are counted.\n" + "If negative, the 0-bits in its two's-complement binary\n" + "representation are counted. If 0, 0 is returned.\n" + "\n" "@lisp\n" "(logcount #b10101010)\n" " @result{} 4\n" @@ -1330,8 +1331,8 @@ static const char scm_ilentab[] = { SCM_DEFINE (scm_integer_length, "integer-length", 1, 0, 0, (SCM n), - "Returns the number of bits neccessary to represent @var{n}.\n\n" - "Example:\n" + "Return the number of bits neccessary to represent @var{n}.\n" + "\n" "@lisp\n" "(integer-length #b10101010)\n" " @result{} 8\n" @@ -2863,7 +2864,7 @@ scm_istring2number (char *str, long len, long radix) SCM_DEFINE (scm_string_to_number, "string->number", 1, 1, 0, (SCM string, SCM radix), - "Returns a number of the maximally precise representation\n" + "Return a number of the maximally precise representation\n" "expressed by the given @var{string}. @var{radix} must be an\n" "exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}\n" "is a default radix that may be overridden by an explicit radix\n" @@ -4228,7 +4229,7 @@ scm_angle (SCM z) SCM_DEFINE (scm_inexact_to_exact, "inexact->exact", 1, 0, 0, (SCM z), - "Returns an exact number that is numerically closest to @var{z}.") + "Return an exact number that is numerically closest to @var{z}.") #define FUNC_NAME s_scm_inexact_to_exact { if (SCM_INUMP (z)) { diff --git a/libguile/objprop.c b/libguile/objprop.c index 17f935e94..41a766c1a 100644 --- a/libguile/objprop.c +++ b/libguile/objprop.c @@ -68,14 +68,14 @@ 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 plist), + (SCM obj, SCM alist), "@deffnx primitive set-procedure-properties! obj alist\n" "Set @var{obj}'s property list to @var{alist}.") #define FUNC_NAME s_scm_set_object_properties_x { - SCM handle = scm_hashq_create_handle_x (scm_object_whash, obj, plist); - SCM_SETCDR (handle, plist); - return plist; + SCM handle = scm_hashq_create_handle_x (scm_object_whash, obj, alist); + SCM_SETCDR (handle, alist); + return alist; } #undef FUNC_NAME @@ -92,10 +92,10 @@ SCM_DEFINE (scm_object_property, "object-property", 2, 0, 0, #undef FUNC_NAME SCM_DEFINE (scm_set_object_property_x, "set-object-property!", 3, 0, 0, - (SCM obj, SCM key, SCM val), + (SCM obj, SCM key, SCM value), "@deffnx primitive set-procedure-property! obj key value\n" - "In @var{obj}'s property list, set the property named @var{key} to\n" - "@var{value}.") + "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 { SCM h; @@ -104,14 +104,14 @@ SCM_DEFINE (scm_set_object_property_x, "set-object-property!", 3, 0, 0, SCM_DEFER_INTS; assoc = scm_assq (key, SCM_CDR (h)); if (SCM_NIMP (assoc)) - SCM_SETCDR (assoc, val); + SCM_SETCDR (assoc, value); else { - assoc = scm_acons (key, val, SCM_CDR (h)); + assoc = scm_acons (key, value, SCM_CDR (h)); SCM_SETCDR (h, assoc); } SCM_ALLOW_INTS; - return val; + return value; } #undef FUNC_NAME diff --git a/libguile/pairs.c b/libguile/pairs.c index 070d08da2..0dee9b6f6 100644 --- a/libguile/pairs.c +++ b/libguile/pairs.c @@ -56,9 +56,9 @@ SCM_DEFINE (scm_cons, "cons", 2, 0, 0, (SCM x, SCM y), - "Returns a newly allocated pair whose car is @var{x} and whose cdr is\n" - "@var{y}. The pair is guaranteed to be different (in the sense of\n" - "@code{eqv?}) from every previously existing object.") + "Return a newly allocated pair whose car is @var{x} and whose\n" + "cdr is @var{y}. The pair is guaranteed to be different (in the\n" + "sense of @code{eq?}) from every previously existing object.") #define FUNC_NAME s_scm_cons { SCM z; @@ -90,7 +90,8 @@ scm_cons2 (SCM w, SCM x, SCM y) SCM_DEFINE (scm_pair_p, "pair?", 1, 0, 0, (SCM x), - "Returns @code{#t} if @var{x} is a pair; otherwise returns @code{#f}.") + "Return @code{#t} if @var{x} is a pair; otherwise return\n" + "@code{#f}.") #define FUNC_NAME s_scm_pair_p { return SCM_BOOL (SCM_CONSP (x)); diff --git a/libguile/ports.c b/libguile/ports.c index c480b7fc8..0762733f4 100644 --- a/libguile/ports.c +++ b/libguile/ports.c @@ -230,20 +230,20 @@ scm_set_port_input_waiting (long tc, int (*input_waiting) (SCM)) SCM_DEFINE (scm_char_ready_p, "char-ready?", 0, 1, 0, - (SCM port), - "Returns @code{#t} if a character is ready on input @var{port} and\n" - "returns @code{#f} otherwise. If @code{char-ready?} returns @code{#t}\n" - "then the next @code{read-char} operation on @var{port} is\n" - "guaranteed not to hang. If @var{port} is a file port at end of\n" - "file then @code{char-ready?} returns @code{#t}.\n" - "@footnote{@code{char-ready?} exists to make it possible for a\n" - "program to accept characters from interactive ports without getting\n" - "stuck waiting for input. Any input editors associated with such ports\n" - "must make sure that characters whose existence has been asserted by\n" - "@code{char-ready?} cannot be rubbed out. If @code{char-ready?} were to\n" - "return @code{#f} at end of file, a port at end of file would be\n" - "indistinguishable from an interactive port that has no ready\n" - "characters.}") + (SCM port), + "Return @code{#t} if a character is ready on input @var{port}\n" + "and return @code{#f} otherwise. If @code{char-ready?} returns\n" + "@code{#t} then the next @code{read-char} operation on\n" + "@var{port} is guaranteed not to hang. If @var{port} is a file\n" + "port at end of file then @code{char-ready?} returns @code{#t}.\n" + "@footnote{@code{char-ready?} exists to make it possible for a\n" + "program to accept characters from interactive ports without\n" + "getting stuck waiting for input. Any input editors associated\n" + "with such ports must make sure that characters whose existence\n" + "has been asserted by @code{char-ready?} cannot be rubbed out.\n" + "If @code{char-ready?} were to return @code{#f} at end of file,\n" + "a port at end of file would be indistinguishable from an\n" + "interactive port that has no ready characters.}") #define FUNC_NAME s_scm_char_ready_p { scm_port *pt; @@ -309,7 +309,7 @@ size_t scm_take_from_input_buffers (SCM port, char *dest, size_t read_len) SCM_DEFINE (scm_drain_input, "drain-input", 1, 0, 0, (SCM port), "Drain @var{port}'s read buffers (including any pushed-back\n" - "characters) and returns the content as a single string.") + "characters) and return the content as a single string.") #define FUNC_NAME s_scm_drain_input { SCM result; @@ -500,7 +500,7 @@ scm_remove_from_port_table (SCM port) SCM_DEFINE (scm_pt_size, "pt-size", 0, 0, 0, (), - "Returns the number of ports in the port table. @code{pt-size}\n" + "Return the number of ports in the port table. @code{pt-size}\n" "is only included in @code{--enable-guile-debug} builds.") #define FUNC_NAME s_scm_pt_size { @@ -510,7 +510,7 @@ SCM_DEFINE (scm_pt_size, "pt-size", 0, 0, 0, SCM_DEFINE (scm_pt_member, "pt-member", 1, 0, 0, (SCM index), - "Returns the port at @var{index} in the port table.\n" + "Return the port at @var{index} in the port table.\n" "@code{pt-member} is only included in\n" "@code{--enable-guile-debug} builds.") #define FUNC_NAME s_scm_pt_member @@ -553,7 +553,7 @@ scm_revealed_count (SCM port) SCM_DEFINE (scm_port_revealed, "port-revealed", 1, 0, 0, (SCM port), - "Returns the revealed count for @var{port}.") + "Return the revealed count for @var{port}.") #define FUNC_NAME s_scm_port_revealed { port = SCM_COERCE_OUTPORT (port); @@ -606,10 +606,10 @@ scm_mode_bits (char *modes) SCM_DEFINE (scm_port_mode, "port-mode", 1, 0, 0, (SCM port), - "Returns the port modes associated with the open port @var{port}. These\n" - "will not necessarily be identical to the modes used when the port was\n" - "opened, since modes such as \"append\" which are used only during\n" - "port creation are not retained.") + "Return the port modes associated with the open port @var{port}.\n" + "These will not necessarily be identical to the modes used when\n" + "the port was opened, since modes such as \"append\" which are\n" + "used only during port creation are not retained.") #define FUNC_NAME s_scm_port_mode { char modes[4]; @@ -641,12 +641,12 @@ SCM_DEFINE (scm_port_mode, "port-mode", 1, 0, 0, */ SCM_DEFINE (scm_close_port, "close-port", 1, 0, 0, (SCM port), - "Close the specified port object. Returns @code{#t} if it successfully\n" - "closes a port or @code{#f} if it was already\n" - "closed. An exception may be raised if an error occurs, for example\n" - "when flushing buffered output.\n" - "See also @ref{Ports and File Descriptors, close}, for a procedure\n" - "which can close file descriptors.") + "Close the specified port object. Return @code{#t} if it\n" + "successfully closes a port or @code{#f} if it was already\n" + "closed. An exception may be raised if an error occurs, for\n" + "example when flushing buffered output. See also @ref{Ports and\n" + "File Descriptors, close}, for a procedure which can close file\n" + "descriptors.") #define FUNC_NAME s_scm_close_port { scm_sizet i; @@ -786,9 +786,9 @@ SCM_DEFINE (scm_close_all_ports_except, "close-all-ports-except", 0, 0, 1, SCM_DEFINE (scm_input_port_p, "input-port?", 1, 0, 0, (SCM x), - "Returns @code{#t} if @var{x} is an input port, otherwise returns\n" - "@code{#f}. Any object satisfying this predicate also satisfies\n" - "@code{port?}.") + "Return @code{#t} if @var{x} is an input port, otherwise return\n" + "@code{#f}. Any object satisfying this predicate also satisfies\n" + "@code{port?}.") #define FUNC_NAME s_scm_input_port_p { if (SCM_IMP (x)) @@ -799,9 +799,9 @@ SCM_DEFINE (scm_input_port_p, "input-port?", 1, 0, 0, SCM_DEFINE (scm_output_port_p, "output-port?", 1, 0, 0, (SCM x), - "Returns @code{#t} if @var{x} is an output port, otherwise returns\n" - "@code{#f}. Any object satisfying this predicate also satisfies\n" - "@code{port?}.") + "Return @code{#t} if @var{x} is an output port, otherwise return\n" + "@code{#f}. Any object satisfying this predicate also satisfies\n" + "@code{port?}.") #define FUNC_NAME s_scm_output_port_p { if (SCM_IMP (x)) @@ -814,7 +814,7 @@ SCM_DEFINE (scm_output_port_p, "output-port?", 1, 0, 0, SCM_DEFINE (scm_port_p, "port?", 1, 0, 0, (SCM x), - "Returns a boolean indicating whether @var{x} is a port.\n" + "Return a boolean indicating whether @var{x} is a port.\n" "Equivalent to @code{(or (input-port? @var{x}) (output-port?\n" "@var{x}))}.") #define FUNC_NAME s_scm_port_p @@ -825,7 +825,8 @@ SCM_DEFINE (scm_port_p, "port?", 1, 0, 0, SCM_DEFINE (scm_port_closed_p, "port-closed?", 1, 0, 0, (SCM port), - "Returns @code{#t} if @var{port} is closed or @code{#f} if it is open.") + "Return @code{#t} if @var{port} is closed or @code{#f} if it is\n" + "open.") #define FUNC_NAME s_scm_port_closed_p { SCM_VALIDATE_PORT (1,port); @@ -835,8 +836,8 @@ SCM_DEFINE (scm_port_closed_p, "port-closed?", 1, 0, 0, SCM_DEFINE (scm_eof_object_p, "eof-object?", 1, 0, 0, (SCM x), - "Returns @code{#t} if @var{x} is an end-of-file object; otherwise\n" - "returns @code{#f}.") + "Return @code{#t} if @var{x} is an end-of-file object; otherwise\n" + "return @code{#f}.") #define FUNC_NAME s_scm_eof_object_p { return SCM_BOOL(SCM_EOF_OBJECT_P (x)); @@ -884,9 +885,9 @@ SCM_DEFINE (scm_flush_all_ports, "flush-all-ports", 0, 0, 0, SCM_DEFINE (scm_read_char, "read-char", 0, 1, 0, (SCM port), - "Returns the next character available from @var{port}, updating\n" - "@var{port} to point to the following character. If no more\n" - "characters are available, an end-of-file object is returned.") + "Return the next character available from @var{port}, updating\n" + "@var{port} to point to the following character. If no more\n" + "characters are available, the end-of-file object is returned.") #define FUNC_NAME s_scm_read_char { int c; @@ -1192,17 +1193,18 @@ scm_ungets (const char *s, int n, SCM port) SCM_DEFINE (scm_peek_char, "peek-char", 0, 1, 0, (SCM port), - "Returns the next character available from @var{port},\n" - "@emph{without} updating @var{port} to point to the following\n" - "character. If no more characters are available, an end-of-file object\n" - "is returned.@footnote{The value returned by a call to @code{peek-char}\n" - "is the same as the value that would have been returned by a call to\n" - "@code{read-char} on the same port. The only difference is that the very\n" - "next call to @code{read-char} or @code{peek-char} on that\n" - "@var{port} will return the value returned by the preceding call to\n" - "@code{peek-char}. In particular, a call to @code{peek-char} on an\n" - "interactive port will hang waiting for input whenever a call to\n" - "@code{read-char} would have hung.}") + "Return the next character available from @var{port},\n" + "@emph{without} updating @var{port} to point to the following\n" + "character. If no more characters are available, the\n" + "end-of-file object is returned.@footnote{The value returned by\n" + "a call to @code{peek-char} is the same as the value that would\n" + "have been returned by a call to @code{read-char} on the same\n" + "port. The only difference is that the very next call to\n" + "@code{read-char} or @code{peek-char} on that @var{port} will\n" + "return the value returned by the preceding call to\n" + "@code{peek-char}. In particular, a call to @code{peek-char} on\n" + "an interactive port will hang waiting for input whenever a call\n" + "to @code{read-char} would have hung.}") #define FUNC_NAME s_scm_peek_char { int c; @@ -1262,11 +1264,13 @@ SCM_DEFINE (scm_unread_string, "unread-string", 2, 0, 0, #undef FUNC_NAME SCM_DEFINE (scm_seek, "seek", 3, 0, 0, - (SCM object, SCM offset, SCM whence), - "Sets the current position of @var{fd/port} to the integer @var{offset},\n" - "which is interpreted according to the value of @var{whence}.\n\n" - "One of the following variables should be supplied\n" - "for @var{whence}:\n" + (SCM fd_port, SCM offset, SCM whence), + "Sets the current position of @var{fd/port} to the integer\n" + "@var{offset}, which is interpreted according to the value of\n" + "@var{whence}.\n" + "\n" + "One of the following variables should be supplied for\n" + "@var{whence}:\n" "@defvar SEEK_SET\n" "Seek from the beginning of the file.\n" "@end defvar\n" @@ -1275,40 +1279,41 @@ SCM_DEFINE (scm_seek, "seek", 3, 0, 0, "@end defvar\n" "@defvar SEEK_END\n" "Seek from the end of the file.\n" - "@end defvar\n\n" - "If @var{fd/port} is a file descriptor, the underlying system call is\n" - "@code{lseek}. @var{port} may be a string port.\n\n" - "The value returned is the new position in the file. This means that\n" - "the current position of a port can be obtained using:\n" - "@smalllisp\n" + "@end defvar\n" + "If @var{fd/port} is a file descriptor, the underlying system\n" + "call is @code{lseek}. @var{port} may be a string port.\n" + "\n" + "The value returned is the new position in the file. This means\n" + "that the current position of a port can be obtained using:\n" + "@lisp\n" "(seek port 0 SEEK_CUR)\n" - "@end smalllisp") + "@end lisp") #define FUNC_NAME s_scm_seek { off_t off; off_t rv; int how; - object = SCM_COERCE_OUTPORT (object); + fd_port = SCM_COERCE_OUTPORT (fd_port); off = SCM_NUM2LONG (2, offset); SCM_VALIDATE_INUM_COPY (3, whence, how); if (how != SEEK_SET && how != SEEK_CUR && how != SEEK_END) SCM_OUT_OF_RANGE (3, whence); - if (SCM_OPPORTP (object)) + if (SCM_OPPORTP (fd_port)) { - scm_ptob_descriptor *ptob = scm_ptobs + SCM_PTOBNUM (object); + scm_ptob_descriptor *ptob = scm_ptobs + SCM_PTOBNUM (fd_port); if (!ptob->seek) SCM_MISC_ERROR ("port is not seekable", - scm_cons (object, SCM_EOL)); + scm_cons (fd_port, SCM_EOL)); else - rv = ptob->seek (object, off, how); + rv = ptob->seek (fd_port, off, how); } else /* file descriptor?. */ { - SCM_VALIDATE_INUM (1,object); - rv = lseek (SCM_INUM (object), off, how); + SCM_VALIDATE_INUM (1,fd_port); + rv = lseek (SCM_INUM (fd_port), off, how); if (rv == -1) SCM_SYSERROR; } @@ -1318,12 +1323,12 @@ SCM_DEFINE (scm_seek, "seek", 3, 0, 0, SCM_DEFINE (scm_truncate_file, "truncate-file", 1, 1, 0, (SCM object, SCM length), - "Truncates the object referred to by @var{obj} to at most @var{size} bytes.\n" - "@var{obj} can be a string containing a file name or an integer file\n" - "descriptor or a port. @var{size} may be omitted if @var{obj} is not\n" - "a file name, in which case the truncation occurs at the current port.\n" - "position.\n\n" - "The return value is unspecified.") + "Truncates the object referred to by @var{object} to at most\n" + "@var{length} bytes. @var{object} can be a string containing a\n" + "file name or an integer file descriptor or a port.\n" + "@var{length} may be omitted if @var{object} is not a file name,\n" + "in which case the truncation occurs at the current port.\n" + "position. The return value is unspecified.") #define FUNC_NAME s_scm_truncate_file { int rv; diff --git a/libguile/posix.c b/libguile/posix.c index d1d54b42b..a3f034e71 100644 --- a/libguile/posix.c +++ b/libguile/posix.c @@ -186,19 +186,19 @@ SCM_SYMBOL (sym_write_pipe, "write pipe"); SCM_DEFINE (scm_pipe, "pipe", 0, 0, 0, (), - "Returns a newly created pipe: a pair of ports which are linked\n" - "together on the local machine. The CAR is the input port and\n" - "the CDR is the output port. Data written (and flushed) to the\n" - "output port can be read from the input port.\n" - "Pipes are commonly used for communication with a newly\n" - "forked child process. The need to flush the output port\n" - "can be avoided by making it unbuffered using @code{setvbuf}.\n\n" - "Writes occur atomically provided the size of the data in\n" - "bytes is not greater than the value of @code{PIPE_BUF}\n" - "Note that the output port is likely to block if too much data\n" - "(typically equal to @code{PIPE_BUF}) has been written but not\n" - "yet read from the input port\n" - ) + "Return a newly created pipe: a pair of ports which are linked\n" + "together on the local machine. The @emph{car} is the input\n" + "port and the @emph{cdr} is the output port. Data written (and\n" + "flushed) to the output port can be read from the input port.\n" + "Pipes are commonly used for communication with a newly forked\n" + "child process. The need to flush the output port can be\n" + "avoided by making it unbuffered using @code{setvbuf}.\n" + "\n" + "Writes occur atomically provided the size of the data in bytes\n" + "is not greater than the value of @code{PIPE_BUF}. Note that\n" + "the output port is likely to block if too much data (typically\n" + "equal to @code{PIPE_BUF}) has been written but not yet read\n" + "from the input port.") #define FUNC_NAME s_scm_pipe { int fd[2], rv; @@ -218,7 +218,8 @@ SCM_DEFINE (scm_pipe, "pipe", 0, 0, 0, #ifdef HAVE_GETGROUPS SCM_DEFINE (scm_getgroups, "getgroups", 0, 0, 0, (), - "Returns a vector of integers representing the current supplimentary group IDs.") + "Return a vector of integers representing the current\n" + "supplimentary group IDs.") #define FUNC_NAME s_scm_getgroups { SCM ans; @@ -473,9 +474,9 @@ SCM_DEFINE (scm_waitpid, "waitpid", 1, 1, 0, SCM_DEFINE (scm_status_exit_val, "status:exit-val", 1, 0, 0, (SCM status), - "Returns the exit status value, as would be\n" - "set if a process ended normally through a\n" - "call to @code{exit} or @code{_exit}, if any, otherwise @code{#f}.") + "Return the exit status value, as would be set if a process\n" + "ended normally through a call to @code{exit} or @code{_exit},\n" + "if any, otherwise @code{#f}.") #define FUNC_NAME s_scm_status_exit_val { int lstatus; @@ -494,8 +495,8 @@ SCM_DEFINE (scm_status_exit_val, "status:exit-val", 1, 0, 0, SCM_DEFINE (scm_status_term_sig, "status:term-sig", 1, 0, 0, (SCM status), - "Returns the signal number which terminated the\n" - "process, if any, otherwise @code{#f}.") + "Return the signal number which terminated the process, if any,\n" + "otherwise @code{#f}.") #define FUNC_NAME s_scm_status_term_sig { int lstatus; @@ -512,8 +513,8 @@ SCM_DEFINE (scm_status_term_sig, "status:term-sig", 1, 0, 0, SCM_DEFINE (scm_status_stop_sig, "status:stop-sig", 1, 0, 0, (SCM status), - "Returns the signal number which stopped the\n" - "process, if any, otherwise @code{#f}.") + "Return the signal number which stopped the process, if any,\n" + "otherwise @code{#f}.") #define FUNC_NAME s_scm_status_stop_sig { int lstatus; @@ -530,7 +531,8 @@ SCM_DEFINE (scm_status_stop_sig, "status:stop-sig", 1, 0, 0, SCM_DEFINE (scm_getppid, "getppid", 0, 0, 0, (), - "Returns an integer representing the process ID of the parent process.") + "Return an integer representing the process ID of the parent\n" + "process.") #define FUNC_NAME s_scm_getppid { return SCM_MAKINUM (0L + getppid ()); @@ -541,7 +543,7 @@ SCM_DEFINE (scm_getppid, "getppid", 0, 0, 0, SCM_DEFINE (scm_getuid, "getuid", 0, 0, 0, (), - "Returns an integer representing the current real user ID.") + "Return an integer representing the current real user ID.") #define FUNC_NAME s_scm_getuid { return SCM_MAKINUM (0L + getuid ()); @@ -552,7 +554,7 @@ SCM_DEFINE (scm_getuid, "getuid", 0, 0, 0, SCM_DEFINE (scm_getgid, "getgid", 0, 0, 0, (), - "Returns an integer representing the current real group ID.") + "Return an integer representing the current real group ID.") #define FUNC_NAME s_scm_getgid { return SCM_MAKINUM (0L + getgid ()); @@ -563,10 +565,10 @@ SCM_DEFINE (scm_getgid, "getgid", 0, 0, 0, SCM_DEFINE (scm_geteuid, "geteuid", 0, 0, 0, (), - "Returns an integer representing the current effective user ID.\n" + "Return an integer representing the current effective user ID.\n" "If the system does not support effective IDs, then the real ID\n" - "is returned. @code{(feature? 'EIDs)} reports whether the system\n" - "supports effective IDs.") + "is returned. @code{(feature? 'EIDs)} reports whether the\n" + "system supports effective IDs.") #define FUNC_NAME s_scm_geteuid { #ifdef HAVE_GETEUID @@ -581,10 +583,10 @@ SCM_DEFINE (scm_geteuid, "geteuid", 0, 0, 0, SCM_DEFINE (scm_getegid, "getegid", 0, 0, 0, (), - "Returns an integer representing the current effective group ID.\n" + "Return an integer representing the current effective group ID.\n" "If the system does not support effective IDs, then the real ID\n" - "is returned. @code{(feature? 'EIDs)} reports whether the system\n" - "supports effective IDs.") + "is returned. @code{(feature? 'EIDs)} reports whether the\n" + "system supports effective IDs.") #define FUNC_NAME s_scm_getegid { #ifdef HAVE_GETEUID @@ -675,7 +677,7 @@ SCM_DEFINE (scm_setegid, "setegid", 1, 0, 0, SCM_DEFINE (scm_getpgrp, "getpgrp", 0, 0, 0, (), - "Returns an integer representing the current process group ID.\n" + "Return an integer representing the current process group ID.\n" "This is the POSIX definition, not BSD.") #define FUNC_NAME s_scm_getpgrp { @@ -724,8 +726,8 @@ SCM_DEFINE (scm_setsid, "setsid", 0, 0, 0, SCM_DEFINE (scm_ttyname, "ttyname", 1, 0, 0, (SCM port), - "Returns a string with the name of the serial terminal device underlying\n" - "@var{port}.") + "Return a string with the name of the serial terminal device\n" + "underlying @var{port}.") #define FUNC_NAME s_scm_ttyname { char *ans; @@ -747,8 +749,8 @@ SCM_DEFINE (scm_ttyname, "ttyname", 1, 0, 0, #ifdef HAVE_CTERMID SCM_DEFINE (scm_ctermid, "ctermid", 0, 0, 0, (), - "Returns a string containing the file name of the controlling terminal\n" - "for the current process.") + "Return a string containing the file name of the controlling\n" + "terminal for the current process.") #define FUNC_NAME s_scm_ctermid { char *result = ctermid (NULL); @@ -762,9 +764,10 @@ SCM_DEFINE (scm_ctermid, "ctermid", 0, 0, 0, #ifdef HAVE_TCGETPGRP SCM_DEFINE (scm_tcgetpgrp, "tcgetpgrp", 1, 0, 0, (SCM port), - "Returns the process group ID of the foreground\n" - "process group associated with the terminal open on the file descriptor\n" - "underlying @var{port}.\n\n" + "Return the process group ID of the foreground process group\n" + "associated with the terminal open on the file descriptor\n" + "underlying @var{port}.\n" + "\n" "If there is no foreground process group, the return value is a\n" "number greater than 1 that does not match the process group ID\n" "of any existing process group. This can happen if all of the\n" @@ -964,8 +967,8 @@ SCM_DEFINE (scm_fork, "primitive-fork", 0, 0, 0, #ifdef HAVE_UNAME SCM_DEFINE (scm_uname, "uname", 0, 0, 0, (), - "Returns an object with some information about the computer system the\n" - "program is running on.") + "Return an object with some information about the computer\n" + "system the program is running on.") #define FUNC_NAME s_scm_uname { struct utsname buf; @@ -989,12 +992,13 @@ SCM_DEFINE (scm_uname, "uname", 0, 0, 0, SCM_DEFINE (scm_environ, "environ", 0, 1, 0, (SCM env), - "If @var{env} is omitted, returns the current environment as a list of strings.\n" - "Otherwise it sets the current environment, which is also the\n" - "default environment for child processes, to the supplied list of strings.\n" - "Each member of @var{env} should be of the form\n" - "@code{NAME=VALUE} and values of @code{NAME} should not be duplicated.\n" - "If @var{env} is supplied then the return value is unspecified.") + "If @var{env} is omitted, return the current environment (in the\n" + "Unix sense) as a list of strings. Otherwise set the current\n" + "environment, which is also the default environment for child\n" + "processes, to the supplied list of strings. Each member of\n" + "@var{env} should be of the form @code{NAME=VALUE} and values of\n" + "@code{NAME} should not be duplicated. If @var{env} is supplied\n" + "then the return value is unspecified.") #define FUNC_NAME s_scm_environ { if (SCM_UNBNDP (env)) @@ -1028,11 +1032,11 @@ SCM_DEFINE (scm_environ, "environ", 0, 1, 0, SCM_DEFINE (scm_tmpnam, "tmpnam", 0, 0, 0, (), - "tmpnam returns a name in the file system that does not match\n" - "any existing file. However there is no guarantee that\n" - "another process will not create the file after tmpnam\n" - "is called. Care should be taken if opening the file,\n" - "e.g., use the O_EXCL open flag or use @code{mkstemp!} instead.") + "Return a name in the file system that does not match any\n" + "existing file. However there is no guarantee that another\n" + "process will not create the file after @code{tmpnam} is called.\n" + "Care should be taken if opening the file, e.g., use the\n" + "@code{O_EXCL} open flag or use @code{mkstemp!} instead.") #define FUNC_NAME s_scm_tmpnam { char name[L_tmpnam]; @@ -1050,12 +1054,11 @@ SCM_DEFINE (scm_tmpnam, "tmpnam", 0, 0, 0, SCM_DEFINE (scm_mkstemp, "mkstemp!", 1, 0, 0, (SCM tmpl), - "mkstemp creates a new unique file in the file system and\n" - "returns a new buffered port open for reading and writing to\n" - "the file. @var{tmpl} is a string specifying where the\n" - "file should be created: it must end with @code{XXXXXX}\n" - "and will be changed in place to return the name of the\n" - "temporary file.\n") + "Create a new unique file in the file system and returns a new\n" + "buffered port open for reading and writing to the file.\n" + "@var{tmpl} is a string specifying where the file should be\n" + "created: it must end with @code{XXXXXX} and will be changed in\n" + "place to return the name of the temporary file.") #define FUNC_NAME s_scm_mkstemp { char *c_tmpl; @@ -1072,18 +1075,16 @@ SCM_DEFINE (scm_mkstemp, "mkstemp!", 1, 0, 0, SCM_DEFINE (scm_utime, "utime", 1, 2, 0, (SCM pathname, SCM actime, SCM modtime), - "@code{utime} sets the access and modification times for\n" - "the file named by @var{path}. If @var{actime} or @var{modtime}\n" - "is not supplied, then the current time is used.\n" - "@var{actime} and @var{modtime}\n" - "must be integer time values as returned by the @code{current-time}\n" - "procedure.\n\n" - "E.g.,\n\n" - "@smalllisp\n" + "@code{utime} sets the access and modification times for the\n" + "file named by @var{path}. If @var{actime} or @var{modtime} is\n" + "not supplied, then the current time is used. @var{actime} and\n" + "@var{modtime} must be integer time values as returned by the\n" + "@code{current-time} procedure.\n" + "@lisp\n" "(utime \"foo\" (- (current-time) 3600))\n" - "@end smalllisp\n\n" - "will set the access time to one hour in the past and the modification\n" - "time to the current time.") + "@end lisp\n" + "will set the access time to one hour in the past and the\n" + "modification time to the current time.") #define FUNC_NAME s_scm_utime { int rv; @@ -1110,17 +1111,17 @@ SCM_DEFINE (scm_utime, "utime", 1, 2, 0, SCM_DEFINE (scm_access, "access?", 2, 0, 0, (SCM path, SCM how), - "Returns @code{#t} if @var{path} corresponds to an existing\n" - "file and the current process\n" - "has the type of access specified by @var{how}, otherwise \n" - "@code{#f}.\n" - "@var{how} should be specified\n" - "using the values of the variables listed below. Multiple values can\n" - "be combined using a bitwise or, in which case @code{#t} will only\n" - "be returned if all accesses are granted.\n\n" - "Permissions are checked using the real id of the current process,\n" - "not the effective id, although it's the effective id which determines\n" - "whether the access would actually be granted.\n\n" + "Return @code{#t} if @var{path} corresponds to an existing file\n" + "and the current process has the type of access specified by\n" + "@var{how}, otherwise @code{#f}. @var{how} should be specified\n" + "using the values of the variables listed below. Multiple\n" + "values can be combined using a bitwise or, in which case\n" + "@code{#t} will only be returned if all accesses are granted.\n" + "\n" + "Permissions are checked using the real id of the current\n" + "process, not the effective id, although it's the effective id\n" + "which determines whether the access would actually be granted.\n" + "\n" "@defvar R_OK\n" "test for read permission.\n" "@end defvar\n" @@ -1147,7 +1148,7 @@ SCM_DEFINE (scm_access, "access?", 2, 0, 0, SCM_DEFINE (scm_getpid, "getpid", 0, 0, 0, (), - "Returns an integer representing the current process ID.") + "Return an integer representing the current process ID.") #define FUNC_NAME s_scm_getpid { return SCM_MAKINUM ((unsigned long) getpid ()); @@ -1187,15 +1188,15 @@ SCM_DEFINE (scm_putenv, "putenv", 1, 0, 0, #ifdef HAVE_SETLOCALE SCM_DEFINE (scm_setlocale, "setlocale", 1, 1, 0, (SCM category, SCM locale), - "If @var{locale} is omitted, returns the current value of the specified\n" - "locale category \n" - "as a system-dependent string.\n" - "@var{category} should be specified using the values @code{LC_COLLATE},\n" - "@code{LC_ALL} etc.\n\n" - "Otherwise the specified locale category is set to\n" - "the string @var{locale}\n" - "and the new value is returned as a system-dependent string. If @var{locale}\n" - "is an empty string, the locale will be set using envirionment variables.") + "If @var{locale} is omitted, return the current value of the\n" + "specified locale category as a system-dependent string.\n" + "@var{category} should be specified using the values\n" + "@code{LC_COLLATE}, @code{LC_ALL} etc.\n" + "\n" + "Otherwise the specified locale category is set to the string\n" + "@var{locale} and the new value is returned as a\n" + "system-dependent string. If @var{locale} is an empty string,\n" + "the locale will be set using envirionment variables.") #define FUNC_NAME s_scm_setlocale { char *clocale; @@ -1233,9 +1234,9 @@ SCM_DEFINE (scm_mknod, "mknod", 4, 0, 0, "to. Its exact interpretation depends on the kind of special file\n" "being created.\n\n" "E.g.,\n" - "@example\n" + "@lisp\n" "(mknod \"/dev/fd0\" 'block-special #o660 (+ (* 2 256) 2))\n" - "@end example\n\n" + "@end lisp\n\n" "The return value is unspecified.") #define FUNC_NAME s_scm_mknod { diff --git a/libguile/ramap.c b/libguile/ramap.c index 21e222c5b..5b50323fb 100644 --- a/libguile/ramap.c +++ b/libguile/ramap.c @@ -1686,19 +1686,19 @@ SCM_DEFINE (scm_array_index_map_x, "array-index-map!", 2, 0, 0, "turn, storing the result in the corresponding element. The value\n" "returned and the order of application are unspecified.\n\n" "One can implement @var{array-indexes} as\n" - "@example\n" + "@lisp\n" "(define (array-indexes array)\n" " (let ((ra (apply make-array #f (array-shape array))))\n" " (array-index-map! ra (lambda x x))\n" " ra))\n" - "@end example\n" + "@end lisp\n" "Another example:\n" - "@example\n" + "@lisp\n" "(define (apl:index-generator n)\n" " (let ((v (make-uniform-vector n 1)))\n" " (array-index-map! v (lambda (i) i))\n" " v))\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_array_index_map_x { scm_sizet i; @@ -1979,11 +1979,12 @@ scm_raequal (SCM ra0, SCM ra1) /* GJB:FIXME:: Why not use SCM_DEFINE1 for array-equal? */ SCM_DEFINE1 (scm_array_equal_p, "array-equal?", scm_tc7_rpsubr, (SCM ra0, SCM ra1), - "Returns @code{#t} iff all arguments are arrays with the same shape, the\n" - "same type, and have corresponding elements which are either\n" - "@code{equal?} or @code{array-equal?}. This function differs from\n" - "@code{equal?} in that a one dimensional shared array may be\n" - "@var{array-equal?} but not @var{equal?} to a vector or uniform vector.") + "Return @code{#t} iff all arguments are arrays with the same\n" + "shape, the same type, and have corresponding elements which are\n" + "either @code{equal?} or @code{array-equal?}. This function\n" + "differs from @code{equal?} in that a one dimensional shared\n" + "array may be @var{array-equal?} but not @var{equal?} to a\n" + "vector or uniform vector.") #define FUNC_NAME s_scm_array_equal_p { } diff --git a/libguile/random.c b/libguile/random.c index f06d984f2..384731478 100644 --- a/libguile/random.c +++ b/libguile/random.c @@ -415,7 +415,8 @@ SCM_DEFINE (scm_seed_to_random_state, "seed->random-state", 1, 0, 0, SCM_DEFINE (scm_random_uniform, "random:uniform", 0, 1, 0, (SCM state), - "Returns a uniformly distributed inexact real random number in [0,1).") + "Return a uniformly distributed inexact real random number in\n" + "[0,1).") #define FUNC_NAME s_scm_random_uniform { if (SCM_UNBNDP (state)) @@ -427,10 +428,10 @@ SCM_DEFINE (scm_random_uniform, "random:uniform", 0, 1, 0, SCM_DEFINE (scm_random_normal, "random:normal", 0, 1, 0, (SCM state), - "Returns an inexact real in a normal distribution.\n" - "The distribution used has mean 0 and standard deviation 1.\n" - "For a normal distribution with mean m and standard deviation\n" - "d use @code{(+ m (* d (random:normal)))}.") + "Return an inexact real in a normal distribution. The\n" + "distribution used has mean 0 and standard deviation 1. For a\n" + "normal distribution with mean m and standard deviation d use\n" + "@code{(+ m (* d (random:normal)))}.") #define FUNC_NAME s_scm_random_normal { if (SCM_UNBNDP (state)) @@ -550,8 +551,9 @@ SCM_DEFINE (scm_random_normal_vector_x, "random:normal-vector!", 1, 1, 0, SCM_DEFINE (scm_random_exp, "random:exp", 0, 1, 0, (SCM state), - "Returns an inexact real in an exponential distribution with mean 1.\n" - "For an exponential distribution with mean u use (* u (random:exp)).") + "Return an inexact real in an exponential distribution with mean\n" + "1. For an exponential distribution with mean u use (* u\n" + "(random:exp)).") #define FUNC_NAME s_scm_random_exp { if (SCM_UNBNDP (state)) diff --git a/libguile/rdelim.c b/libguile/rdelim.c index 40f65b938..3ebd39955 100644 --- a/libguile/rdelim.c +++ b/libguile/rdelim.c @@ -268,13 +268,13 @@ SCM_DEFINE (scm_read_line, "%read-line", 0, 1, 0, SCM_DEFINE (scm_write_line, "write-line", 1, 1, 0, (SCM obj, SCM port), - "Display @var{obj} and a newline character to @var{port}. If @var{port}\n" - "is not specified, @code{(current-output-port)} is used. This function\n" - "is equivalent to:\n\n" - "@smalllisp\n" + "Display @var{obj} and a newline character to @var{port}. If\n" + "@var{port} is not specified, @code{(current-output-port)} is\n" + "used. This function is equivalent to:\n" + "@lisp\n" "(display obj [port])\n" "(newline [port])\n" - "@end smalllisp") + "@end lisp") #define FUNC_NAME s_scm_write_line { scm_display (obj, port); diff --git a/libguile/regex-posix.c b/libguile/regex-posix.c index 5fafba687..8174217a7 100644 --- a/libguile/regex-posix.c +++ b/libguile/regex-posix.c @@ -134,49 +134,54 @@ scm_regexp_error_msg (int regerrno, regex_t *rx) } SCM_DEFINE (scm_regexp_p, "regexp?", 1, 0, 0, - (SCM x), - "Return @code{#t} if @var{obj} is a compiled regular expression, or\n" - "@code{#f} otherwise.") + (SCM obj), + "Return @code{#t} if @var{obj} is a compiled regular expression,\n" + "or @code{#f} otherwise.") #define FUNC_NAME s_scm_regexp_p { - return SCM_BOOL(SCM_RGXP (x)); + return SCM_BOOL(SCM_RGXP (obj)); } #undef FUNC_NAME SCM_DEFINE (scm_make_regexp, "make-regexp", 1, 0, 1, (SCM pat, SCM flags), - "Compile the regular expression described by @var{str}, and return the\n" - "compiled regexp structure. If @var{str} does not describe a legal\n" - "regular expression, @code{make-regexp} throws a\n" - "@code{regular-expression-syntax} error.\n\n" - "The @var{flag} arguments change the behavior of the compiled regexp.\n" - "The following flags may be supplied:\n\n" + "Compile the regular expression described by @var{pat}, and\n" + "return the compiled regexp structure. If @var{pat} does not\n" + "describe a legal regular expression, @code{make-regexp} throws\n" + "a @code{regular-expression-syntax} error.\n" + "\n" + "The @var{flags} arguments change the behavior of the compiled\n" + "regular expression. The following flags may be supplied:\n" + "\n" "@table @code\n" "@item regexp/icase\n" - "Consider uppercase and lowercase letters to be the same when matching.\n\n" + "Consider uppercase and lowercase letters to be the same when\n" + "matching.\n" "@item regexp/newline\n" - "If a newline appears in the target string, then permit the @samp{^} and\n" - "@samp{$} operators to match immediately after or immediately before the\n" - "newline, respectively. Also, the @samp{.} and @samp{[^...]} operators\n" - "will never match a newline character. The intent of this flag is to\n" - "treat the target string as a buffer containing many lines of text, and\n" - "the regular expression as a pattern that may match a single one of those\n" - "lines.\n\n" + "If a newline appears in the target string, then permit the\n" + "@samp{^} and @samp{$} operators to match immediately after or\n" + "immediately before the newline, respectively. Also, the\n" + "@samp{.} and @samp{[^...]} operators will never match a newline\n" + "character. The intent of this flag is to treat the target\n" + "string as a buffer containing many lines of text, and the\n" + "regular expression as a pattern that may match a single one of\n" + "those lines.\n" "@item regexp/basic\n" "Compile a basic (``obsolete'') regexp instead of the extended\n" - "(``modern'') regexps that are the default. Basic regexps do not\n" - "consider @samp{|}, @samp{+} or @samp{?} to be special characters, and\n" - "require the @samp{@{...@}} and @samp{(...)} metacharacters to be\n" - "backslash-escaped (@pxref{Backslash Escapes}). There are several other\n" - "differences between basic and extended regular expressions, but these\n" - "are the most significant.\n\n" + "(``modern'') regexps that are the default. Basic regexps do\n" + "not consider @samp{|}, @samp{+} or @samp{?} to be special\n" + "characters, and require the @samp{@{...@}} and @samp{(...)}\n" + "metacharacters to be backslash-escaped (@pxref{Backslash\n" + "Escapes}). There are several other differences between basic\n" + "and extended regular expressions, but these are the most\n" + "significant.\n" "@item regexp/extended\n" - "Compile an extended regular expression rather than a basic regexp. This\n" - "is the default behavior; this flag will not usually be needed. If a\n" - "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") + "Compile an extended regular expression rather than a basic\n" + "regexp. This is the default behavior; this flag will not\n" + "usually be needed. If a call to @code{make-regexp} includes\n" + "both @code{regexp/basic} and @code{regexp/extended} flags, the\n" + "one which comes last will override the earlier one.\n" + "@end table") #define FUNC_NAME s_scm_make_regexp { SCM flag; @@ -220,10 +225,11 @@ SCM_DEFINE (scm_make_regexp, "make-regexp", 1, 0, 1, SCM_DEFINE (scm_regexp_exec, "regexp-exec", 2, 2, 0, (SCM rx, SCM str, SCM start, SCM flags), - "Match the compiled regular expression @var{regexp} against @code{str}.\n" - "If the optional integer @var{start} argument is provided, begin matching\n" - "from that position in the string. Return a match structure describing\n" - "the results of the match, or @code{#f} if no match could be found.") + "Match the compiled regular expression @var{rx} against\n" + "@code{str}. If the optional integer @var{start} argument is\n" + "provided, begin matching from that position in the string.\n" + "Return a match structure describing the results of the match,\n" + "or @code{#f} if no match could be found.") #define FUNC_NAME s_scm_regexp_exec { int status, nmatches, offset; diff --git a/libguile/root.c b/libguile/root.c index 6779f6779..a0d092030 100644 --- a/libguile/root.c +++ b/libguile/root.c @@ -334,7 +334,7 @@ SCM_DEFINE (scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0, "Before calling @var{thunk}, the dynamic-wind chain is un-wound back to\n" "the root and a new chain started for @var{thunk}. Therefore, this call\n" "may not do what you expect:\n\n" - "@example\n" + "@lisp\n" ";; Almost certainly a bug:\n" "(with-output-to-port\n" " some-port\n\n" @@ -344,7 +344,7 @@ SCM_DEFINE (scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0, " (display 'fnord)\n" " (newline))\n" " (lambda (errcode) errcode))))\n" - "@end example\n\n" + "@end lisp\n\n" "The problem is, on what port will @samp{fnord} be displayed? You\n" "might expect that because of the @code{with-output-to-port} that\n" "it will be displayed on the port bound to @code{some-port}. But it\n" diff --git a/libguile/simpos.c b/libguile/simpos.c index e847ce0d5..a03ec6c30 100644 --- a/libguile/simpos.c +++ b/libguile/simpos.c @@ -68,11 +68,13 @@ extern int system(); #ifdef HAVE_SYSTEM SCM_DEFINE (scm_system, "system", 0, 1, 0, (SCM cmd), - "Executes @var{cmd} using the operating system's \"command processor\".\n" - "Under Unix this is usually the default shell @code{sh}. The value\n" - "returned is @var{cmd}'s exit status as returned by @code{waitpid}, which\n" - "can be interpreted using the functions above.\n\n" - "If @code{system} is called without arguments, it returns a boolean\n" + "Execute @var{cmd} using the operating system's \"command\n" + "processor\". Under Unix this is usually the default shell\n" + "@code{sh}. The value returned is @var{cmd}'s exit status as\n" + "returned by @code{waitpid}, which can be interpreted using the\n" + "functions above.\n" + "\n" + "If @code{system} is called without arguments, return a boolean\n" "indicating whether the command processor is available.") #define FUNC_NAME s_scm_system { diff --git a/libguile/socket.c b/libguile/socket.c index e923b1b18..f6b404bd3 100644 --- a/libguile/socket.c +++ b/libguile/socket.c @@ -84,9 +84,9 @@ SCM_DEFINE (scm_htons, "htons", 1, 0, 0, (SCM in), - "Returns a new integer from @var{value} by converting from host to\n" - "network order. @var{value} must be within the range of a C unsigned\n" - "short integer.") + "Return a new integer from @var{value} by converting from host\n" + "to network order. @var{value} must be within the range of a C\n" + "unsigned short integer.") #define FUNC_NAME s_scm_htons { unsigned short c_in; @@ -101,9 +101,9 @@ SCM_DEFINE (scm_htons, "htons", 1, 0, 0, SCM_DEFINE (scm_ntohs, "ntohs", 1, 0, 0, (SCM in), - "Returns a new integer from @var{value} by converting from network to\n" - "host order. @var{value} must be within the range of a C unsigned short\n" - "integer.") + "Return a new integer from @var{value} by converting from\n" + "network to host order. @var{value} must be within the range of\n" + "a C unsigned short integer.") #define FUNC_NAME s_scm_ntohs { unsigned short c_in; @@ -118,9 +118,9 @@ SCM_DEFINE (scm_ntohs, "ntohs", 1, 0, 0, SCM_DEFINE (scm_htonl, "htonl", 1, 0, 0, (SCM in), - "Returns a new integer from @var{value} by converting from host to\n" - "network order. @var{value} must be within the range of a C unsigned\n" - "long integer.") + "Return a new integer from @var{value} by converting from host\n" + "to network order. @var{value} must be within the range of a C\n" + "unsigned long integer.") #define FUNC_NAME s_scm_htonl { unsigned long c_in = SCM_NUM2ULONG (1,in); @@ -130,9 +130,9 @@ SCM_DEFINE (scm_htonl, "htonl", 1, 0, 0, SCM_DEFINE (scm_ntohl, "ntohl", 1, 0, 0, (SCM in), - "Returns a new integer from @var{value} by converting from network to\n" - "host order. @var{value} must be within the range of a C unsigned\n" - "long integer.") + "Return a new integer from @var{value} by converting from\n" + "network to host order. @var{value} must be within the range of\n" + "a C unsigned long integer.") #define FUNC_NAME s_scm_ntohl { unsigned long c_in = SCM_NUM2ULONG (1,in); @@ -146,16 +146,19 @@ SCM_SYMBOL (sym_socket, "socket"); SCM_DEFINE (scm_socket, "socket", 3, 0, 0, (SCM family, SCM style, SCM proto), - "Returns a new socket port of the type specified by @var{family}, @var{style}\n" - "and @var{protocol}. All three parameters are integers. Typical values\n" - "for @var{family} are the values of @code{AF_UNIX}\n" - "and @code{AF_INET}. Typical values for @var{style} are\n" - "the values of @code{SOCK_STREAM}, @code{SOCK_DGRAM} and @code{SOCK_RAW}.\n\n" + "Return a new socket port of the type specified by @var{family},\n" + "@var{style} and @var{protocol}. All three parameters are\n" + "integers. Typical values for @var{family} are the values of\n" + "@code{AF_UNIX} and @code{AF_INET}. Typical values for\n" + "@var{style} are the values of @code{SOCK_STREAM},\n" + "@code{SOCK_DGRAM} and @code{SOCK_RAW}.\n" + "\n" "@var{protocol} can be obtained from a protocol name using\n" - "@code{getprotobyname}. A value of\n" - "zero specifies the default protocol, which is usually right.\n\n" - "A single socket port cannot by used for communication until\n" - "it has been connected to another socket.") + "@code{getprotobyname}. A value of zero specifies the default\n" + "protocol, which is usually right.\n" + "\n" + "A single socket port cannot by used for communication until it\n" + "has been connected to another socket.") #define FUNC_NAME s_scm_socket { int fd; @@ -173,11 +176,11 @@ SCM_DEFINE (scm_socket, "socket", 3, 0, 0, #ifdef HAVE_SOCKETPAIR SCM_DEFINE (scm_socketpair, "socketpair", 3, 0, 0, (SCM family, SCM style, SCM proto), - "Returns a pair of connected (but unnamed) socket ports of the type specified\n" - "by @var{family}, @var{style} and @var{protocol}.\n" - "Many systems support only\n" - "socket pairs of the @code{AF_UNIX} family. Zero is likely to be\n" - "the only meaningful value for @var{protocol}.") + "Return a pair of connected (but unnamed) socket ports of the\n" + "type specified by @var{family}, @var{style} and @var{protocol}.\n" + "Many systems support only socket pairs of the @code{AF_UNIX}\n" + "family. Zero is likely to be the only meaningful value for\n" + "@var{protocol}.") #define FUNC_NAME s_scm_socketpair { int fam; @@ -199,14 +202,15 @@ SCM_DEFINE (scm_socketpair, "socketpair", 3, 0, 0, SCM_DEFINE (scm_getsockopt, "getsockopt", 3, 0, 0, (SCM sock, SCM level, SCM optname), - "Returns the value of a particular socket option for the socket\n" - "port @var{socket}. @var{level} is an integer code for type of option\n" - "being requested, e.g., @code{SOL_SOCKET} for socket-level options.\n" - "@var{optname} is an\n" - "integer code for the option required and should be specified using one of\n" - "the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.\n\n" - "The returned value is typically an integer but @code{SO_LINGER} returns a\n" - "pair of integers.") + "Return the value of a particular socket option for the socket\n" + "port @var{socket}. @var{level} is an integer code for type of\n" + "option being requested, e.g., @code{SOL_SOCKET} for\n" + "socket-level options. @var{optname} is an integer code for the\n" + "option required and should be specified using one of the\n" + "symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.\n" + "\n" + "The returned value is typically an integer but @code{SO_LINGER}\n" + "returns a pair of integers.") #define FUNC_NAME s_scm_getsockopt { int fd; @@ -663,9 +667,9 @@ SCM_DEFINE (scm_accept, "accept", 1, 0, 0, SCM_DEFINE (scm_getsockname, "getsockname", 1, 0, 0, (SCM sock), - "Returns the address of @var{socket}, in the same form as the object\n" - "returned by @code{accept}. On many systems the address of a socket\n" - "in the @code{AF_FILE} namespace cannot be read.") + "Return the address of @var{socket}, in the same form as the\n" + "object returned by @code{accept}. On many systems the address\n" + "of a socket in the @code{AF_FILE} namespace cannot be read.") #define FUNC_NAME s_scm_getsockname { int fd; @@ -689,10 +693,10 @@ SCM_DEFINE (scm_getsockname, "getsockname", 1, 0, 0, SCM_DEFINE (scm_getpeername, "getpeername", 1, 0, 0, (SCM sock), - "Returns the address of the socket that the socket @var{socket} is connected to,\n" - "in the same form as the object\n" - "returned by @code{accept}. On many systems the address of a socket\n" - "in the @code{AF_FILE} namespace cannot be read.") + "Return the address of the socket that the socket @var{socket}\n" + "is connected to, in the same form as the object returned by\n" + "@code{accept}. On many systems the address of a socket in the\n" + "@code{AF_FILE} namespace cannot be read.") #define FUNC_NAME s_scm_getpeername { int fd; @@ -778,23 +782,27 @@ SCM_DEFINE (scm_send, "send", 2, 1, 0, SCM_DEFINE (scm_recvfrom, "recvfrom!", 2, 3, 0, (SCM sock, SCM str, SCM flags, SCM start, SCM end), - "Returns data from the socket port @var{socket} and also information about\n" - "where the data was received from. @var{socket} must already\n" - "be bound to the address from which data is to be received.\n" - "@code{str}, is a string into which\n" - "the data will be written. The size of @var{str} limits the amount of\n" - "data which can be received: in the case of packet\n" - "protocols, if a packet larger than this limit is encountered then some data\n" - "will be irrevocably lost.\n\n" - "The optional @var{flags} argument is a value or\n" - "bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.\n\n" - "The value returned is a pair: the CAR is the number of bytes read from\n" - "the socket and the CDR an address object in the same form as returned by\n" - "@code{accept}.\n\n" - "The @var{start} and @var{end} arguments specify a substring of @var{str}\n" - "to which the data should be written.\n\n" - "Note that the data is read directly from the socket file descriptor:\n" - "any unread buffered port data is ignored.") + "Return data from the socket port @var{socket} and also\n" + "information about where the data was received from.\n" + "@var{socket} must already be bound to the address from which\n" + "data is to be received. @code{str}, is a string into which the\n" + "data will be written. The size of @var{str} limits the amount\n" + "of data which can be received: in the case of packet protocols,\n" + "if a packet larger than this limit is encountered then some\n" + "data will be irrevocably lost.\n" + "\n" + "The optional @var{flags} argument is a value or bitwise OR of\n" + "@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.\n" + "\n" + "The value returned is a pair: the @emph{car} is the number of\n" + "bytes read from the socket and the @emph{cdr} an address object\n" + "in the same form as returned by @code{accept}.\n" + "\n" + "The @var{start} and @var{end} arguments specify a substring of\n" + "@var{str} to which the data should be written.\n" + "\n" + "Note that the data is read directly from the socket file\n" + "descriptor: any unread buffered port data is ignored.") #define FUNC_NAME s_scm_recvfrom { int rv; diff --git a/libguile/stime.c b/libguile/stime.c index d723da8d0..ce1e6006e 100644 --- a/libguile/stime.c +++ b/libguile/stime.c @@ -138,7 +138,8 @@ timet scm_your_base = 0; 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.") + "Return the number of time units since the interpreter was\n" + "started.") #define FUNC_NAME s_scm_get_internal_real_time { #ifdef HAVE_FTIME @@ -163,9 +164,10 @@ SCM_DEFINE (scm_get_internal_real_time, "get-internal-real-time", 0, 0, 0, #ifdef HAVE_TIMES SCM_DEFINE (scm_times, "times", 0, 0, 0, (void), - "Returns an object with information about real and processor time.\n" - "The following procedures accept such an object as an argument and\n" - "return a selected component:\n\n" + "Return an object with information about real and processor\n" + "time. The following procedures accept such an object as an\n" + "argument and return a selected component:\n" + "\n" "@table @code\n" "@item tms:clock\n" "The current real time, expressed as time units relative to an\n" @@ -173,12 +175,14 @@ SCM_DEFINE (scm_times, "times", 0, 0, 0, "@item tms:utime\n" "The CPU time units used by the calling process.\n" "@item tms:stime\n" - "The CPU time units used by the system on behalf of the calling process.\n" + "The CPU time units used by the system on behalf of the calling\n" + "process.\n" "@item tms:cutime\n" - "The CPU time units used by terminated child processes of the calling\n" - "process, whose status has been collected (e.g., using @code{waitpid}).\n" + "The CPU time units used by terminated child processes of the\n" + "calling process, whose status has been collected (e.g., using\n" + "@code{waitpid}).\n" "@item tms:cstime\n" - "Similarly, the CPU times units used by the system on behalf of \n" + "Similarly, the CPU times units used by the system on behalf of\n" "terminated child processes.\n" "@end table") #define FUNC_NAME s_scm_times @@ -210,8 +214,9 @@ scm_c_get_internal_run_time () SCM_DEFINE (scm_get_internal_run_time, "get-internal-run-time", 0, 0, 0, (void), - "Returns the number of time units of processor time used by the interpreter.\n" - "Both \"system\" and \"user\" time are included but subprocesses are not.") + "Return the number of time units of processor time used by the\n" + "interpreter. Both @emph{system} and @emph{user} time are\n" + "included but subprocesses are not.") #define FUNC_NAME s_scm_get_internal_run_time { return scm_long2num (scm_c_get_internal_run_time ()); @@ -220,8 +225,8 @@ SCM_DEFINE (scm_get_internal_run_time, "get-internal-run-time", 0, 0, 0, SCM_DEFINE (scm_current_time, "current-time", 0, 0, 0, (void), - "Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding\n" - "leap seconds.") + "Return the number of seconds since 1970-01-01 00:00:00 UTC,\n" + "excluding leap seconds.") #define FUNC_NAME s_scm_current_time { timet timv; @@ -236,9 +241,10 @@ SCM_DEFINE (scm_current_time, "current-time", 0, 0, 0, SCM_DEFINE (scm_gettimeofday, "gettimeofday", 0, 0, 0, (void), - "Returns a pair containing the number of seconds and microseconds since\n" - "1970-01-01 00:00:00 UTC, excluding leap seconds. Note: whether true\n" - "microsecond resolution is available depends on the operating system.") + "Return a pair containing the number of seconds and microseconds\n" + "since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:\n" + "whether true microsecond resolution is available depends on the\n" + "operating system.") #define FUNC_NAME s_scm_gettimeofday { #ifdef HAVE_GETTIMEOFDAY @@ -334,11 +340,11 @@ restorezone (SCM zone, char **oldenv, const char *subr) SCM_DEFINE (scm_localtime, "localtime", 1, 1, 0, (SCM time, SCM zone), - "Returns an object representing the broken down components of @var{time},\n" - "an integer like the one returned by @code{current-time}. The time zone\n" - "for the calculation is optionally specified by @var{zone} (a string),\n" - "otherwise the @code{TZ} environment variable or the system default is\n" - "used.") + "Return an object representing the broken down components of\n" + "@var{time}, an integer like the one returned by\n" + "@code{current-time}. The time zone for the calculation is\n" + "optionally specified by @var{zone} (a string), otherwise the\n" + "@code{TZ} environment variable or the system default is used.") #define FUNC_NAME s_scm_localtime { timet itime; @@ -408,9 +414,9 @@ SCM_DEFINE (scm_localtime, "localtime", 1, 1, 0, SCM_DEFINE (scm_gmtime, "gmtime", 1, 0, 0, (SCM time), - "Returns an object representing the broken down components of @var{time},\n" - "an integer like the one returned by @code{current-time}. The values\n" - "are calculated for UTC.") + "Return an object representing the broken down components of\n" + "@var{time}, an integer like the one returned by\n" + "@code{current-time}. The values are calculated for UTC.") #define FUNC_NAME s_scm_gmtime { timet itime; diff --git a/libguile/strings.c b/libguile/strings.c index cf8ddca28..70d831907 100644 --- a/libguile/strings.c +++ b/libguile/strings.c @@ -58,7 +58,7 @@ SCM_DEFINE (scm_string_p, "string?", 1, 0, 0, (SCM obj), - "Returns @code{#t} iff @var{obj} is a string, else returns\n" + "Return @code{#t} iff @var{obj} is a string, else returns\n" "@code{#f}.") #define FUNC_NAME s_scm_string_p { @@ -77,12 +77,12 @@ SCM_DEFINE (scm_read_only_string_p, "read-only-string?", 1, 0, 0, "Return true if @var{obj} can be read as a string,\n\n" "This illustrates the difference between @code{string?} and\n" "@code{read-only-string?}:\n\n" - "@example\n" + "@lisp\n" "(string? \"a string\") @result{} #t\n" "(string? 'a-symbol) @result{} #f\n\n" "(read-only-string? \"a string\") @result{} #t\n" "(read-only-string? 'a-symbol) @result{} #t\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_read_only_string_p { return SCM_BOOL(SCM_ROSTRINGP (obj)); @@ -96,7 +96,7 @@ SCM_REGISTER_PROC (s_scm_list_to_string, "list->string", 1, 0, 0, scm_string); SCM_DEFINE (scm_string, "string", 0, 0, 1, (SCM chrs), "@deffnx primitive list->string chrs\n" - "Returns a newly allocated string composed of the arguments,\n" + "Return a newly allocated string composed of the arguments,\n" "@var{chrs}.") #define FUNC_NAME s_scm_string { @@ -390,14 +390,14 @@ SCM_DEFINE (scm_string_append, "string-append", 0, 0, 1, */ SCM_DEFINE (scm_make_shared_substring, "make-shared-substring", 1, 2, 0, - (SCM str, SCM frm, SCM to), - "Return a shared substring of @var{str}. The semantics are the same as\n" - "for the @code{substring} function: the shared substring returned\n" - "includes all of the text from @var{str} between indexes @var{start}\n" - "(inclusive) and @var{end} (exclusive). If @var{end} is omitted, it\n" - "defaults to the end of @var{str}. The shared substring returned by\n" - "@code{make-shared-substring} occupies the same storage space as\n" - "@var{str}.") + (SCM str, SCM start, SCM end), + "Return a shared substring of @var{str}. The semantics are the\n" + "same as for the @code{substring} function: the shared substring\n" + "returned includes all of the text from @var{str} between\n" + "indexes @var{start} (inclusive) and @var{end} (exclusive). If\n" + "@var{end} is omitted, it defaults to the end of @var{str}. The\n" + "shared substring returned by @code{make-shared-substring}\n" + "occupies the same storage space as @var{str}.") #define FUNC_NAME s_scm_make_shared_substring { long f; @@ -406,11 +406,11 @@ SCM_DEFINE (scm_make_shared_substring, "make-shared-substring", 1, 2, 0, SCM len_str; SCM_VALIDATE_ROSTRING (1,str); - SCM_VALIDATE_INUM_DEF_COPY (2,frm,0,f); - SCM_VALIDATE_INUM_DEF_COPY (3,to,SCM_ROLENGTH(str),t); + SCM_VALIDATE_INUM_DEF_COPY (2,start,0,f); + SCM_VALIDATE_INUM_DEF_COPY (3,end,SCM_ROLENGTH(str),t); - SCM_ASSERT_RANGE (2,frm,(f >= 0)); - SCM_ASSERT_RANGE (3,to, (f <= t) && (t <= SCM_ROLENGTH (str))); + SCM_ASSERT_RANGE (2,start,(f >= 0)); + SCM_ASSERT_RANGE (3,end, (f <= t) && (t <= SCM_ROLENGTH (str))); SCM_NEWCELL (answer); SCM_NEWCELL (len_str); diff --git a/libguile/strop.c b/libguile/strop.c index 9740986d2..48f3c33b6 100644 --- a/libguile/strop.c +++ b/libguile/strop.c @@ -104,21 +104,16 @@ SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0, "@var{str}. The optional integer arguments @var{frm} and\n" "@var{to} limit the search to a portion of the string. This\n" "procedure essentially implements the @code{index} or\n" - "@code{strchr} functions from the C library.\n\n" - "(qdocs:) Returns\n" - "the index of @var{char} in @var{str}, or @code{#f} if the\n" - "@var{char} isn't in @var{str}. If @var{frm} is given and not\n" - "@code{#f}, it is used as the starting index; if @var{to} is\n" - "given and not @code{#f}, it is used as the ending index\n" - "(exclusive).\n\n" - "@example\n" + "@code{strchr} functions from the C library.\n" + "\n" + "@lisp\n" "(string-index \"weiner\" #\\e)\n" "@result{} 1\n\n" "(string-index \"weiner\" #\\e 2)\n" "@result{} 4\n\n" "(string-index \"weiner\" #\\e 2 4)\n" "@result{} #f\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_string_index { int pos; @@ -136,20 +131,19 @@ SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0, SCM_DEFINE (scm_string_rindex, "string-rindex", 2, 2, 0, (SCM str, SCM chr, SCM frm, SCM to), - "Like @code{string-index}, but search from the right of the string rather\n" - "than from the left. This procedure essentially implements the\n" - "@code{rindex} or @code{strrchr} functions from the C library.\n\n" - "(qdocs:) The same as @code{string-index}, except it gives the rightmost occurance\n" - "of @var{char} in the range [@var{frm}, @var{to}-1], which defaults to\n" - "the entire string.\n\n" - "@example\n" + "Like @code{string-index}, but search from the right of the\n" + "string rather than from the left. This procedure essentially\n" + "implements the @code{rindex} or @code{strrchr} functions from\n" + "the C library.\n" + "\n" + "@lisp\n" "(string-rindex \"weiner\" #\\e)\n" "@result{} 4\n\n" "(string-rindex \"weiner\" #\\e 2 4)\n" "@result{} #f\n\n" "(string-rindex \"weiner\" #\\e 2 5)\n" "@result{} 4\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_string_rindex { int pos; @@ -179,7 +173,7 @@ Moves a substring of @var{str1}, from @var{start1} to @var{end1} (@var{end1} is exclusive), into @var{str2}, starting at @var{start2}. Allows overlapping strings. -@example +@lisp (define x (make-string 10 #\a)) (define y "bcd") (substring-move-left! x 2 5 y 0) @@ -198,7 +192,7 @@ y (substring-move-left! y 2 5 y 3) y @result{} "abccccg" -@end example +@end lisp */ /* @@ -210,7 +204,7 @@ it hasn't made it into the guile tree]. Does much the same thing as @code{substring-move-left!}, except it starts moving at the end of the sequence, rather than the beginning. -@example +@lisp (define y "abcdefg") (substring-move-right! y 2 5 y 0) y @@ -220,7 +214,7 @@ y (substring-move-right! y 2 5 y 3) y @result{} "abccdeg" -@end example +@end lisp */ SCM_DEFINE (scm_substring_move_x, "substring-move!", 5, 0, 0, @@ -269,15 +263,15 @@ SCM_DEFINE (scm_substring_move_x, "substring-move!", 5, 0, 0, SCM_DEFINE (scm_substring_fill_x, "substring-fill!", 4, 0, 0, (SCM str, SCM start, SCM end, SCM fill), - "Change every character in @var{str} between @var{start} and @var{end} to\n" - "@var{fill-char}.\n\n" - "(qdocs:) Destructively fills @var{str}, from @var{start} to @var{end}, with @var{fill}.\n\n" - "@example\n" + "Change every character in @var{str} between @var{start} and\n" + "@var{end} to @var{fill}.\n" + "\n" + "@lisp\n" "(define y \"abcdefg\")\n" "(substring-fill! y 1 3 #\\r)\n" "y\n" "@result{} \"arrdefg\"\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_substring_fill_x { long i, e; @@ -296,15 +290,13 @@ SCM_DEFINE (scm_substring_fill_x, "substring-fill!", 4, 0, 0, SCM_DEFINE (scm_string_null_p, "string-null?", 1, 0, 0, (SCM str), - "Return @code{#t} if @var{str}'s length is nonzero, and @code{#f}\n" - "otherwise.\n\n" - "(qdocs:) Returns @code{#t} if @var{str} is empty, else returns @code{#f}.\n\n" - "@example\n" - "(string-null? \"\")\n" - "@result{} #t\n\n" - "(string-null? y)\n" - "@result{} #f\n" - "@end example") + "Return @code{#t} if @var{str}'s length is nonzero, and\n" + "@code{#f} otherwise.\n" + "@lisp\n" + "(string-null? \"\") @result{} #t\n" + "y @result{} \"foo\"\n" + "(string-null? y) @result{} #f\n" + "@end lisp") #define FUNC_NAME s_scm_string_null_p { SCM_VALIDATE_STRING (1,str); @@ -343,7 +335,7 @@ string_copy (SCM str) SCM_DEFINE (scm_string_copy, "string-copy", 1, 0, 0, (SCM str), - "Returns a newly allocated copy of the given @var{string}. (r5rs)") + "Return a newly allocated copy of the given @var{string}.") #define FUNC_NAME s_scm_string_copy { SCM_VALIDATE_STRING (1, str); @@ -355,8 +347,8 @@ SCM_DEFINE (scm_string_copy, "string-copy", 1, 0, 0, SCM_DEFINE (scm_string_fill_x, "string-fill!", 2, 0, 0, (SCM str, SCM chr), - "Stores @var{char} in every element of the given @var{string} and returns an\n" - "unspecified value. (r5rs)") + "Store @var{char} in every element of the given @var{string} and\n" + "return an unspecified value.") #define FUNC_NAME s_scm_string_fill_x { register char *dst, c; diff --git a/libguile/strorder.c b/libguile/strorder.c index 2dee2b800..bbf4ba30f 100644 --- a/libguile/strorder.c +++ b/libguile/strorder.c @@ -54,14 +54,14 @@ SCM_DEFINE1 (scm_string_equal_p, "string=?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Lexicographic equality predicate; \n" - "Returns @code{#t} if the two strings are the same length and\n" - "contain the same characters in the same positions, otherwise\n" - "returns @code{#f}. (r5rs)\n\n" - "The procedure @code{string-ci=?} treats upper and lower case\n" - "letters as though they were the same character, but\n" - "@code{string=?} treats upper and lower case as distinct\n" - "characters.") + "Lexicographic equality predicate; return @code{#t} if the two\n" + "strings are the same length and contain the same characters in\n" + "the same positions, otherwise return @code{#f}.\n" + "\n" + "The procedure @code{string-ci=?} treats upper and lower case\n" + "letters as though they were the same character, but\n" + "@code{string=?} treats upper and lower case as distinct\n" + "characters.") #define FUNC_NAME s_scm_string_equal_p { scm_sizet length; @@ -93,10 +93,10 @@ SCM_DEFINE1 (scm_string_equal_p, "string=?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_ci_equal_p, "string-ci=?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Case-insensitive string equality predicate; returns @code{#t}\n" - "if the two strings are the same length and their component\n" - "characters match (ignoring case) at each position; otherwise\n" - "returns @code{#f}. (r5rs)") + "Case-insensitive string equality predicate; return @code{#t} if\n" + "the two strings are the same length and their component\n" + "characters match (ignoring case) at each position; otherwise\n" + "return @code{#f}.") #define FUNC_NAME s_scm_string_ci_equal_p { scm_sizet length; @@ -152,8 +152,8 @@ string_less_p (SCM s1, SCM s2) SCM_DEFINE1 (scm_string_less_p, "string<?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Lexicographic ordering predicate; returns @code{#t} if\n" - "@var{s1} is lexicographically less than @var{s2}. (r5rs)") + "Lexicographic ordering predicate; return @code{#t} if @var{s1}\n" + "is lexicographically less than @var{s2}.") #define FUNC_NAME s_scm_string_less_p { SCM_VALIDATE_STRING (1, s1); @@ -166,9 +166,8 @@ SCM_DEFINE1 (scm_string_less_p, "string<?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_leq_p, "string<=?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Lexicographic ordering predicate; returns @code{#t} if\n" - "@var{s1} is lexicographically less than or equal to @var{s2}.\n" - "(r5rs)") + "Lexicographic ordering predicate; return @code{#t} if @var{s1}\n" + "is lexicographically less than or equal to @var{s2}.") #define FUNC_NAME s_scm_string_leq_p { SCM_VALIDATE_STRING (1, s1); @@ -181,8 +180,8 @@ SCM_DEFINE1 (scm_string_leq_p, "string<=?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_gr_p, "string>?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Lexicographic ordering predicate; returns @code{#t} if\n" - "@var{s1} is lexicographically greater than @var{s2}. (r5rs)") + "Lexicographic ordering predicate; return @code{#t} if @var{s1}\n" + "is lexicographically greater than @var{s2}.") #define FUNC_NAME s_scm_string_gr_p { SCM_VALIDATE_STRING (1, s1); @@ -195,9 +194,8 @@ SCM_DEFINE1 (scm_string_gr_p, "string>?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_geq_p, "string>=?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Lexicographic ordering predicate; returns @code{#t} if\n" - "@var{s1} is lexicographically greater than or equal to\n" - "@var{s2}. (r5rs)") + "Lexicographic ordering predicate; return @code{#t} if @var{s1}\n" + "is lexicographically greater than or equal to @var{s2}.") #define FUNC_NAME s_scm_string_geq_p { SCM_VALIDATE_STRING (1, s1); @@ -234,9 +232,9 @@ string_ci_less_p (SCM s1, SCM s2) SCM_DEFINE1 (scm_string_ci_less_p, "string-ci<?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Case insensitive lexicographic ordering predicate;\n" - "returns @code{#t} if @var{s1} is lexicographically less than\n" - "@var{s2} regardless of case. (r5rs)") + "Case insensitive lexicographic ordering predicate; return\n" + "@code{#t} if @var{s1} is lexicographically less than @var{s2}\n" + "regardless of case.") #define FUNC_NAME s_scm_string_ci_less_p { SCM_VALIDATE_STRING (1, s1); @@ -249,9 +247,9 @@ SCM_DEFINE1 (scm_string_ci_less_p, "string-ci<?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_ci_leq_p, "string-ci<=?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Case insensitive lexicographic ordering predicate;\n" - "returns @code{#t} if @var{s1} is lexicographically less than\n" - "or equal to @var{s2} regardless of case. (r5rs)") + "Case insensitive lexicographic ordering predicate; return\n" + "@code{#t} if @var{s1} is lexicographically less than or equal\n" + "to @var{s2} regardless of case.") #define FUNC_NAME s_scm_string_ci_leq_p { SCM_VALIDATE_STRING (1, s1); @@ -264,9 +262,9 @@ SCM_DEFINE1 (scm_string_ci_leq_p, "string-ci<=?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_ci_gr_p, "string-ci>?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Case insensitive lexicographic ordering predicate;\n" - "returns @code{#t} if @var{s1} is lexicographically greater\n" - "than @var{s2} regardless of case. (r5rs)") + "Case insensitive lexicographic ordering predicate; return\n" + "@code{#t} if @var{s1} is lexicographically greater than\n" + "@var{s2} regardless of case.") #define FUNC_NAME s_scm_string_ci_gr_p { SCM_VALIDATE_STRING (1, s1); @@ -279,9 +277,9 @@ SCM_DEFINE1 (scm_string_ci_gr_p, "string-ci>?", scm_tc7_rpsubr, SCM_DEFINE1 (scm_string_ci_geq_p, "string-ci>=?", scm_tc7_rpsubr, (SCM s1, SCM s2), - "Case insensitive lexicographic ordering predicate;\n" - "returns @code{#t} if @var{s1} is lexicographically greater\n" - "than or equal to @var{s2} regardless of case. (r5rs)") + "Case insensitive lexicographic ordering predicate; return\n" + "@code{#t} if @var{s1} is lexicographically greater than or\n" + "equal to @var{s2} regardless of case.") #define FUNC_NAME s_scm_string_ci_geq_p { SCM_VALIDATE_STRING (1, s1); diff --git a/libguile/strports.c b/libguile/strports.c index c1a20e60b..3a8faaa51 100644 --- a/libguile/strports.c +++ b/libguile/strports.c @@ -365,21 +365,21 @@ SCM_DEFINE (scm_call_with_output_string, "call-with-output-string", 1, 0, 0, #undef FUNC_NAME SCM_DEFINE (scm_call_with_input_string, "call-with-input-string", 2, 0, 0, - (SCM str, SCM proc), - "Calls the one-argument procedure @var{proc} with a newly created input\n" - "port from which @var{string}'s contents may be read. The value yielded\n" - "by the @var{proc} is returned.") + (SCM string, SCM proc), + "Calls the one-argument procedure @var{proc} with a newly\n" + "created input port from which @var{string}'s contents may be\n" + "read. The value yielded by the @var{proc} is returned.") #define FUNC_NAME s_scm_call_with_input_string { - SCM p = scm_mkstrport(SCM_INUM0, str, SCM_OPN | SCM_RDNG, FUNC_NAME); + SCM p = scm_mkstrport(SCM_INUM0, string, SCM_OPN | SCM_RDNG, FUNC_NAME); return scm_apply (proc, p, scm_listofnull); } #undef FUNC_NAME SCM_DEFINE (scm_open_input_string, "open-input-string", 1, 0, 0, (SCM str), - "Takes a string and returns an input port that delivers\n" - "characters from the string. The port can be closed by\n" + "Take a string and return an input port that delivers characters\n" + "from the string. The port can be closed by\n" "@code{close-input-port}, though its storage will be reclaimed\n" "by the garbage collector if it becomes inaccessible.") #define FUNC_NAME s_scm_open_input_string @@ -391,7 +391,7 @@ SCM_DEFINE (scm_open_input_string, "open-input-string", 1, 0, 0, SCM_DEFINE (scm_open_output_string, "open-output-string", 0, 0, 0, (void), - "Returns an output port that will accumulate characters for\n" + "Return an output port that will accumulate characters for\n" "retrieval by @code{get-output-string}. The port can be closed\n" "by the procedure @code{close-output-port}, though its storage\n" "will be reclaimed by the garbage collector if it becomes\n" @@ -411,7 +411,7 @@ SCM_DEFINE (scm_open_output_string, "open-output-string", 0, 0, 0, SCM_DEFINE (scm_get_output_string, "get-output-string", 1, 0, 0, (SCM port), "Given an output port created by @code{open-output-string},\n" - "returns a string consisting of the characters that have been\n" + "return a string consisting of the characters that have been\n" "output to the port so far.") #define FUNC_NAME s_scm_get_output_string { diff --git a/libguile/struct.c b/libguile/struct.c index b57d1996f..3f86c22cf 100644 --- a/libguile/struct.c +++ b/libguile/struct.c @@ -503,7 +503,7 @@ SCM_DEFINE (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1, "sub-system: one vtable-vtable working as the root and one or several\n" "\"types\", each with a set of \"instances\". (The vtable-vtable should be\n" "compared to the class <class> which is the class of itself.)\n\n" - "@example\n" + "@lisp\n" "(define ball-root (make-vtable-vtable \"pr\" 0))\n\n" "(define (make-ball-type ball-color)\n" " (make-struct ball-root 0\n" @@ -520,7 +520,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 lisp\n") #define FUNC_NAME s_scm_make_vtable_vtable { SCM fields; diff --git a/libguile/symbols.c b/libguile/symbols.c index 061e91811..0f47fa3be 100644 --- a/libguile/symbols.c +++ b/libguile/symbols.c @@ -418,8 +418,8 @@ scm_symbol_value0 (const char *name) SCM_DEFINE (scm_symbol_p, "symbol?", 1, 0, 0, (SCM obj), - "Returns @code{#t} if @var{obj} is a symbol, otherwise returns\n" - "@code{#f}. (r5rs)") + "Return @code{#t} if @var{obj} is a symbol, otherwise return\n" + "@code{#f}.") #define FUNC_NAME s_scm_symbol_p { return SCM_BOOL (SCM_SYMBOLP (obj)); @@ -428,24 +428,26 @@ SCM_DEFINE (scm_symbol_p, "symbol?", 1, 0, 0, SCM_DEFINE (scm_symbol_to_string, "symbol->string", 1, 0, 0, (SCM s), - "Returns the name of @var{symbol} as a string. If the symbol\n" - "was part of an object returned as the value of a literal\n" - "expression (section @pxref{Literal expressions,,,r4rs, The\n" - "Revised^4 Report on Scheme}) or by a call to the @code{read}\n" - "procedure, and its name contains alphabetic characters, then\n" - "the string returned will contain characters in the\n" - "implementation's preferred standard case---some implementations\n" - "will prefer upper case, others lower case. If the symbol was\n" - "returned by @code{string->symbol}, the case of characters in\n" - "the string returned will be the same as the case in the string\n" - "that was passed to @code{string->symbol}. It is an error to\n" - "apply mutation procedures like @code{string-set!} to strings\n" - "returned by this procedure. (r5rs)\n\n" + "Return the name of @var{symbol} as a string. If the symbol was\n" + "part of an object returned as the value of a literal expression\n" + "(section @pxref{Literal expressions,,,r4rs, The Revised^4\n" + "Report on Scheme}) or by a call to the @code{read} procedure,\n" + "and its name contains alphabetic characters, then the string\n" + "returned will contain characters in the implementation's\n" + "preferred standard case---some implementations will prefer\n" + "upper case, others lower case. If the symbol was returned by\n" + "@code{string->symbol}, the case of characters in the string\n" + "returned will be the same as the case in the string that was\n" + "passed to @code{string->symbol}. It is an error to apply\n" + "mutation procedures like @code{string-set!} to strings returned\n" + "by this procedure.\n" + "\n" "The following examples assume that the implementation's\n" - "standard case is lower case:\n\n" + "standard case is lower case:\n" + "\n" "@lisp\n" - "(symbol->string 'flying-fish) @result{} \"flying-fish\"\n" - "(symbol->string 'Martin) @result{} \"martin\"\n" + "(symbol->string 'flying-fish) @result{} \"flying-fish\"\n" + "(symbol->string 'Martin) @result{} \"martin\"\n" "(symbol->string\n" " (string->symbol \"Malvina\")) @result{} \"Malvina\"\n" "@end lisp") @@ -458,14 +460,17 @@ SCM_DEFINE (scm_symbol_to_string, "symbol->string", 1, 0, 0, SCM_DEFINE (scm_string_to_symbol, "string->symbol", 1, 0, 0, - (SCM s), - "Returns the symbol whose name is @var{string}. This procedure\n" + (SCM string), + "Return the symbol whose name is @var{string}. This procedure\n" "can create symbols with names containing special characters or\n" "letters in the non-standard case, but it is usually a bad idea\n" - "to create such because in some implementations of Scheme they\n" - "cannot be read as themselves. See @code{symbol->string}.\n\n" + "to create such symbols because in some implementations of\n" + "Scheme they cannot be read as themselves. See\n" + "@code{symbol->string}.\n" + "\n" "The following examples assume that the implementation's\n" - "standard case is lower case:\n\n" + "standard case is lower case:\n" + "\n" "@lisp\n" "(eq? 'mISSISSIppi 'mississippi) @result{} #t\n" "(string->symbol \"mISSISSIppi\") @result{} @r{the symbol with name \"mISSISSIppi\"}\n" @@ -478,8 +483,9 @@ SCM_DEFINE (scm_string_to_symbol, "string->symbol", 1, 0, 0, "@end lisp") #define FUNC_NAME s_scm_string_to_symbol { - SCM_VALIDATE_STRING (1, s); - return scm_mem2symbol (SCM_STRING_CHARS (s), SCM_STRING_LENGTH (s)); + SCM_VALIDATE_STRING (1, string); + return scm_mem2symbol (SCM_STRING_CHARS (string), + SCM_STRING_LENGTH (string)); } #undef FUNC_NAME diff --git a/libguile/throw.c b/libguile/throw.c index e0e921dcd..fce8d8e0f 100644 --- a/libguile/throw.c +++ b/libguile/throw.c @@ -514,37 +514,41 @@ scm_handle_by_throw (void *handler_data, SCM tag, SCM args) /* the Scheme-visible CATCH and LAZY-CATCH functions */ SCM_DEFINE (scm_catch, "catch", 3, 0, 0, - (SCM tag, SCM thunk, SCM handler), + (SCM key, SCM thunk, SCM handler), "Invoke @var{thunk} in the dynamic context of @var{handler} for\n" - "exceptions matching @var{key}. If thunk throws to the symbol @var{key},\n" - "then @var{handler} is invoked this way:\n\n" - "@example\n" + "exceptions matching @var{key}. If thunk throws to the symbol\n" + "@var{key}, then @var{handler} is invoked this way:\n" + "@lisp\n" "(handler key args ...)\n" - "@end example\n\n" - "@var{key} is a symbol or #t.\n\n" - "@var{thunk} takes no arguments. If @var{thunk} returns normally, that\n" - "is the return value of @code{catch}.\n\n" - "Handler is invoked outside the scope of its own @code{catch}. If\n" - "@var{handler} again throws to the same key, a new handler from further\n" - "up the call chain is invoked.\n\n" - "If the key is @code{#t}, then a throw to @emph{any} symbol will match\n" - "this call to @code{catch}.") + "@end lisp\n" + "\n" + "@var{key} is a symbol or @code{#t}.\n" + "\n" + "@var{thunk} takes no arguments. If @var{thunk} returns\n" + "normally, that is the return value of @code{catch}.\n" + "\n" + "Handler is invoked outside the scope of its own @code{catch}.\n" + "If @var{handler} again throws to the same key, a new handler\n" + "from further up the call chain is invoked.\n" + "\n" + "If the key is @code{#t}, then a throw to @emph{any} symbol will\n" + "match this call to @code{catch}.") #define FUNC_NAME s_scm_catch { struct scm_body_thunk_data c; - SCM_ASSERT (SCM_SYMBOLP (tag) || SCM_EQ_P (tag, SCM_BOOL_T), - tag, SCM_ARG1, FUNC_NAME); + SCM_ASSERT (SCM_SYMBOLP (key) || SCM_EQ_P (key, SCM_BOOL_T), + key, SCM_ARG1, FUNC_NAME); - c.tag = tag; + c.tag = key; c.body_proc = thunk; /* scm_internal_catch takes care of all the mechanics of setting up - a catch tag; we tell it to call scm_body_thunk to run the body, + a catch key; we tell it to call scm_body_thunk to run the body, and scm_handle_by_proc to deal with any throws to this catch. The former receives a pointer to c, telling it how to behave. The latter receives a pointer to HANDLER, so it knows who to call. */ - return scm_internal_catch (tag, + return scm_internal_catch (key, scm_body_thunk, &c, scm_handle_by_proc, &handler); } @@ -552,7 +556,7 @@ SCM_DEFINE (scm_catch, "catch", 3, 0, 0, SCM_DEFINE (scm_lazy_catch, "lazy-catch", 3, 0, 0, - (SCM tag, SCM thunk, SCM handler), + (SCM key, SCM thunk, SCM handler), "This behaves exactly like @code{catch}, except that it does\n" "not unwind the stack (this is the major difference), and if\n" "handler returns, its value is returned from the throw.") @@ -560,19 +564,19 @@ SCM_DEFINE (scm_lazy_catch, "lazy-catch", 3, 0, 0, { struct scm_body_thunk_data c; - SCM_ASSERT (SCM_SYMBOLP (tag) || SCM_EQ_P (tag, SCM_BOOL_T), - tag, SCM_ARG1, FUNC_NAME); + SCM_ASSERT (SCM_SYMBOLP (key) || SCM_EQ_P (key, SCM_BOOL_T), + key, SCM_ARG1, FUNC_NAME); - c.tag = tag; + c.tag = key; c.body_proc = thunk; /* scm_internal_lazy_catch takes care of all the mechanics of - setting up a lazy catch tag; we tell it to call scm_body_thunk to + setting up a lazy catch key; we tell it to call scm_body_thunk to run the body, and scm_handle_by_proc to deal with any throws to this catch. The former receives a pointer to c, telling it how to behave. The latter receives a pointer to HANDLER, so it knows who to call. */ - return scm_internal_lazy_catch (tag, + return scm_internal_lazy_catch (key, scm_body_thunk, &c, scm_handle_by_proc, &handler); } diff --git a/libguile/unif.c b/libguile/unif.c index 9255abb37..62e75bf49 100644 --- a/libguile/unif.c +++ b/libguile/unif.c @@ -251,8 +251,8 @@ scm_make_uve (long k, SCM prot) SCM_DEFINE (scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0, - (SCM v), - "Returns the number of elements in @var{uve}.") + (SCM v), + "Return the number of elements in @var{uve}.") #define FUNC_NAME s_scm_uniform_vector_length { SCM_ASRTGO (SCM_NIMP (v), badarg1); @@ -284,9 +284,9 @@ SCM_DEFINE (scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0, SCM_DEFINE (scm_array_p, "array?", 1, 1, 0, (SCM v, SCM prot), - "Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.\n\n" - "The @var{prototype} argument is used with uniform arrays and is described\n" - "elsewhere.") + "Return @code{#t} if the @var{obj} is an array, and @code{#f} if\n" + "not. The @var{prototype} argument is used with uniform arrays\n" + "and is described elsewhere.") #define FUNC_NAME s_scm_array_p { int nprot; @@ -356,8 +356,8 @@ SCM_DEFINE (scm_array_p, "array?", 1, 1, 0, SCM_DEFINE (scm_array_rank, "array-rank", 1, 0, 0, (SCM ra), - "Returns the number of dimensions of @var{obj}. If @var{obj} is not an\n" - "array, @code{0} is returned.") + "Return the number of dimensions of @var{obj}. If @var{obj} is\n" + "not an array, @code{0} is returned.") #define FUNC_NAME s_scm_array_rank { if (SCM_IMP (ra)) @@ -393,9 +393,9 @@ SCM_DEFINE (scm_array_dimensions, "array-dimensions", 1, 0, 0, (SCM ra), "@code{Array-dimensions} is similar to @code{array-shape} but replaces\n" "elements with a @code{0} minimum with one greater than the maximum. So:\n" - "@example\n" + "@lisp\n" "(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_array_dimensions { SCM res = SCM_EOL; @@ -578,12 +578,12 @@ scm_shap2ra (SCM args, const char *what) } SCM_DEFINE (scm_dimensions_to_uniform_array, "dimensions->uniform-array", 2, 1, 0, - (SCM dims, SCM prot, SCM fill), + (SCM dims, SCM prot, SCM fill), "@deffnx primitive make-uniform-vector length prototype [fill]\n" - "Creates and returns a uniform array or vector of type corresponding to\n" - "@var{prototype} with dimensions @var{dims} or length @var{length}. If\n" - "@var{fill} is supplied, it's used to fill the array, otherwise \n" - "@var{prototype} is used.") + "Create and return a uniform array or vector of type\n" + "corresponding to @var{prototype} with dimensions @var{dims} or\n" + "length @var{length}. If @var{fill} is supplied, it's used to\n" + "fill the array, otherwise @var{prototype} is used.") #define FUNC_NAME s_scm_dimensions_to_uniform_array { scm_sizet k; @@ -660,7 +660,7 @@ SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1, "the new array into coordinates in the old array. A @var{mapper} must be\n" "linear, and its range must stay within the bounds of the old array, but\n" "it can be otherwise arbitrary. A simple example:\n" - "@example\n" + "@lisp\n" "(define fred (make-array #f 8 8))\n" "(define freds-diagonal\n" " (make-shared-array fred (lambda (i) (list i i)) 8))\n" @@ -669,7 +669,7 @@ SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1, "(define freds-center\n" " (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))\n" "(array-ref freds-center 0 0) @result{} foo\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_make_shared_array { SCM ra; @@ -783,23 +783,25 @@ SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1, /* args are RA . DIMS */ SCM_DEFINE (scm_transpose_array, "transpose-array", 1, 0, 1, (SCM ra, SCM args), - "Returns an array sharing contents with @var{array}, but with dimensions\n" - "arranged in a different order. There must be one @var{dim} argument for\n" - "each dimension of @var{array}. @var{dim0}, @var{dim1}, @dots{} should\n" - "be integers between 0 and the rank of the array to be returned. Each\n" - "integer in that range must appear at least once in the argument list.\n\n" - "The values of @var{dim0}, @var{dim1}, @dots{} correspond to dimensions\n" - "in the array to be returned, their positions in the argument list to\n" - "dimensions of @var{array}. Several @var{dim}s may have the same value,\n" - "in which case the returned array will have smaller rank than\n" - "@var{array}.\n\n" - "examples:\n" - "@example\n" + "Return an array sharing contents with @var{array}, but with\n" + "dimensions arranged in a different order. There must be one\n" + "@var{dim} argument for each dimension of @var{array}.\n" + "@var{dim0}, @var{dim1}, @dots{} should be integers between 0\n" + "and the rank of the array to be returned. Each integer in that\n" + "range must appear at least once in the argument list.\n" + "\n" + "The values of @var{dim0}, @var{dim1}, @dots{} correspond to\n" + "dimensions in the array to be returned, their positions in the\n" + "argument list to dimensions of @var{array}. Several @var{dim}s\n" + "may have the same value, in which case the returned array will\n" + "have smaller rank than @var{array}.\n" + "\n" + "@lisp\n" "(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))\n" "(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)\n" "(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}\n" " #2((a 4) (b 5) (c 6))\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_transpose_array { SCM res, vargs, *ve = &vargs; @@ -903,12 +905,12 @@ SCM_DEFINE (scm_enclose_array, "enclose-array", 1, 0, 1, "@code{eq?}. The value returned by @var{array-prototype} when given an\n" "enclosed array is unspecified.\n\n" "examples:\n" - "@example\n" + "@lisp\n" "(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}\n" " #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>\n\n" "(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}\n" " #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_enclose_array { SCM axv, res, ra_inr; @@ -991,7 +993,8 @@ SCM_DEFINE (scm_enclose_array, "enclose-array", 1, 0, 1, SCM_DEFINE (scm_array_in_bounds_p, "array-in-bounds?", 1, 0, 1, (SCM v, SCM args), - "Returns @code{#t} if its arguments would be acceptable to array-ref.") + "Return @code{#t} if its arguments would be acceptable to\n" + "@code{array-ref}.") #define FUNC_NAME s_scm_array_in_bounds_p { SCM ind = SCM_EOL; @@ -1076,7 +1079,8 @@ SCM_REGISTER_PROC(s_array_ref, "array-ref", 1, 0, 1, scm_uniform_vector_ref); SCM_DEFINE (scm_uniform_vector_ref, "uniform-vector-ref", 2, 0, 0, (SCM v, SCM args), "@deffnx primitive array-ref v . args\n" - "Returns the element at the @code{(index1, index2)} element in @var{array}.") + "Return the element at the @code{(index1, index2)} element in\n" + "@var{array}.") #define FUNC_NAME s_scm_uniform_vector_ref { long pos; @@ -1770,7 +1774,7 @@ static char cnt_tab[16] = SCM_DEFINE (scm_bit_count, "bit-count", 2, 0, 0, (SCM b, SCM bitvector), - "Returns the number of occurrences of the boolean @var{b} in\n" + "Return the number of occurrences of the boolean @var{b} in\n" "@var{bitvector}.") #define FUNC_NAME s_scm_bit_count { @@ -1808,9 +1812,9 @@ SCM_DEFINE (scm_bit_count, "bit-count", 2, 0, 0, SCM_DEFINE (scm_bit_position, "bit-position", 3, 0, 0, (SCM item, SCM v, SCM k), - "Returns the minimum index of an occurrence of @var{bool} in @var{bv}\n" - "which is at least @var{k}. If no @var{bool} occurs within the specified\n" - "range @code{#f} is returned.") + "Return the minimum index of an occurrence of @var{bool} in\n" + "@var{bv} which is at least @var{k}. If no @var{bool} occurs\n" + "within the specified range @code{#f} is returned.") #define FUNC_NAME s_scm_bit_position { long i, lenw, xbits, pos; @@ -1928,10 +1932,10 @@ SCM_DEFINE (scm_bit_set_star_x, "bit-set*!", 3, 0, 0, SCM_DEFINE (scm_bit_count_star, "bit-count*", 3, 0, 0, (SCM v, SCM kv, SCM obj), - "Returns\n" - "@example\n" + "Return\n" + "@lisp\n" "(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).\n" - "@end example\n" + "@end lisp\n" "@var{bv} is not modified.") #define FUNC_NAME s_scm_bit_count_star { @@ -2074,7 +2078,8 @@ ra2l (SCM ra,scm_sizet base,scm_sizet k) SCM_DEFINE (scm_array_to_list, "array->list", 1, 0, 0, (SCM v), - "Returns a list consisting of all the elements, in order, of @var{array}.") + "Return a list consisting of all the elements, in order, of\n" + "@var{array}.") #define FUNC_NAME s_scm_array_to_list { SCM res = SCM_EOL; @@ -2164,9 +2169,10 @@ static int l2ra(SCM lst, SCM ra, scm_sizet base, scm_sizet k); SCM_DEFINE (scm_list_to_uniform_array, "list->uniform-array", 3, 0, 0, (SCM ndim, SCM prot, SCM lst), "@deffnx procedure list->uniform-vector prot lst\n" - "Returns a uniform array of the type indicated by prototype @var{prot}\n" - "with elements the same as those of @var{lst}. Elements must be of the\n" - "appropriate type, no coercions are done.") + "Return a uniform array of the type indicated by prototype\n" + "@var{prot} with elements the same as those of @var{lst}.\n" + "Elements must be of the appropriate type, no coercions are\n" + "done.") #define FUNC_NAME s_scm_list_to_uniform_array { SCM shp = SCM_EOL; @@ -2515,8 +2521,8 @@ tail: SCM_DEFINE (scm_array_prototype, "array-prototype", 1, 0, 0, (SCM ra), - "Returns an object that would produce an array of the same type as\n" - "@var{array}, if used as the @var{prototype} for\n" + "Return an object that would produce an array of the same type\n" + "as @var{array}, if used as the @var{prototype} for\n" "@code{make-uniform-array}.") #define FUNC_NAME s_scm_array_prototype { diff --git a/libguile/vectors.c b/libguile/vectors.c index 280b2eedf..e21c5b0aa 100644 --- a/libguile/vectors.c +++ b/libguile/vectors.c @@ -138,8 +138,8 @@ scm_vector_set_length_x (SCM vect, SCM len) SCM_DEFINE (scm_vector_p, "vector?", 1, 0, 0, (SCM obj), - "Returns @code{#t} if @var{obj} is a vector, otherwise returns\n" - "@code{#f}. (r5rs)") + "Return @code{#t} if @var{obj} is a vector, otherwise return\n" + "@code{#f}.") #define FUNC_NAME s_scm_vector_p { if (SCM_IMP (obj)) @@ -149,7 +149,7 @@ SCM_DEFINE (scm_vector_p, "vector?", 1, 0, 0, #undef FUNC_NAME SCM_GPROC (s_vector_length, "vector-length", 1, 0, 0, scm_vector_length, g_vector_length); -/* Returns the number of elements in @var{vector} as an exact integer. (r5rs) */ +/* Returns the number of elements in @var{vector} as an exact integer. */ SCM scm_vector_length (SCM v) { @@ -170,10 +170,11 @@ SCM_REGISTER_PROC (s_list_to_vector, "list->vector", 1, 0, 0, scm_vector); SCM_DEFINE (scm_vector, "vector", 0, 0, 1, (SCM l), "@deffnx primitive list->vector l\n" - "Returns a newly allocated vector whose elements contain the\n" - "given arguments. Analogous to @code{list}. (r5rs)\n\n" + "Return a newly allocated vector whose elements contain the\n" + "given arguments. Analogous to @code{list}.\n" + "\n" "@lisp\n" - "(vector 'a 'b 'c) @result{} #(a b c)\n" + "(vector 'a 'b 'c) @result{} #(a b c)\n" "@end lisp") #define FUNC_NAME s_scm_vector { @@ -257,9 +258,10 @@ scm_vector_set_x (SCM v, SCM k, SCM obj) SCM_DEFINE (scm_make_vector, "make-vector", 1, 1, 0, (SCM k, SCM fill), - "Returns a newly allocated vector of @var{k} elements. If a second\n" - "argument is given, then each element is initialized to @var{fill}.\n" - "Otherwise the initial contents of each element is unspecified. (r5rs)") + "Return a newly allocated vector of @var{k} elements. If a\n" + "second argument is given, then each element is initialized to\n" + "@var{fill}. Otherwise the initial contents of each element is\n" + "unspecified.") #define FUNC_NAME s_scm_make_vector { if (SCM_UNBNDP (fill)) @@ -309,9 +311,10 @@ scm_c_make_vector (unsigned long int k, SCM fill) SCM_DEFINE (scm_vector_to_list, "vector->list", 1, 0, 0, - (SCM v), - "@samp{Vector->list} returns a newly allocated list of the\n" - "objects contained in the elements of @var{vector}. (r5rs)\n\n" + (SCM v), + "Return a newly allocated list of the objects contained in the\n" + "elements of @var{vector}.\n" + "\n" "@lisp\n" "(vector->list '#(dah dah didah)) @result{} (dah dah didah)\n" "(list->vector '(dididit dah)) @result{} #(dididit dah)\n" @@ -330,9 +333,9 @@ SCM_DEFINE (scm_vector_to_list, "vector->list", 1, 0, 0, SCM_DEFINE (scm_vector_fill_x, "vector-fill!", 2, 0, 0, - (SCM v, SCM fill_x), - "Stores @var{fill} in every element of @var{vector}.\n" - "The value returned by @code{vector-fill!} is unspecified. (r5rs)") + (SCM v, SCM fill), + "Store @var{fill} in every element of @var{vector}. The value\n" + "returned by @code{vector-fill!} is unspecified.") #define FUNC_NAME s_scm_vector_fill_x { register long i; @@ -340,7 +343,7 @@ SCM_DEFINE (scm_vector_fill_x, "vector-fill!", 2, 0, 0, SCM_VALIDATE_VECTOR (1,v); data = SCM_VELTS(v); for(i = SCM_VECTOR_LENGTH(v) - 1; i >= 0; i--) - data[i] = fill_x; + data[i] = fill; return SCM_UNSPECIFIED; } #undef FUNC_NAME diff --git a/libguile/version.c b/libguile/version.c index 98c8691e9..85cc484aa 100644 --- a/libguile/version.c +++ b/libguile/version.c @@ -83,11 +83,11 @@ SCM_DEFINE (scm_version, "version", 0, 0, 0, "@deffnx primitive minor-version\n" "Return a string describing Guile's version number, or its major or minor\n" "version numbers, respectively.\n\n" - "@example\n" + "@lisp\n" "(version) @result{} \"1.3a\"\n" "(major-version) @result{} \"1\"\n" "(minor-version) @result{} \"3a\"\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_version { return scm_makfrom0str (GUILE_VERSION); diff --git a/libguile/vports.c b/libguile/vports.c index 962759b23..9a4975aff 100644 --- a/libguile/vports.c +++ b/libguile/vports.c @@ -147,10 +147,11 @@ sf_close (SCM port) SCM_DEFINE (scm_make_soft_port, "make-soft-port", 2, 0, 0, (SCM pv, SCM modes), - "Returns a port capable of receiving or delivering characters as\n" + "Return a port capable of receiving or delivering characters as\n" "specified by the @var{modes} string (@pxref{File Ports,\n" - "open-file}). @var{vector} must be a vector of length 6. Its components\n" - "are as follows:\n\n" + "open-file}). @var{pv} must be a vector of length 5. Its\n" + "components are as follows:\n" + "\n" "@enumerate 0\n" "@item\n" "procedure accepting one character for output\n" @@ -162,15 +163,19 @@ SCM_DEFINE (scm_make_soft_port, "make-soft-port", 2, 0, 0, "thunk for getting one character\n" "@item\n" "thunk for closing port (not by garbage collection)\n" - "@end enumerate\n\n" + "@end enumerate\n" + "\n" "For an output-only port only elements 0, 1, 2, and 4 need be\n" - "procedures. For an input-only port only elements 3 and 4 need be\n" - "procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful\n" - "operation for them to perform.\n\n" - "If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input,\n" - "eof-object?, ,r4rs, The Revised^4 Report on Scheme}) it indicates that\n" - "the port has reached end-of-file. For example:\n\n" - "@example\n" + "procedures. For an input-only port only elements 3 and 4 need\n" + "be procedures. Thunks 2 and 4 can instead be @code{#f} if\n" + "there is no useful operation for them to perform.\n" + "\n" + "If thunk 3 returns @code{#f} or an @code{eof-object}\n" + "(@pxref{Input, eof-object?, ,r4rs, The Revised^4 Report on\n" + "Scheme}) it indicates that the port has reached end-of-file.\n" + "For example:\n" + "\n" + "@lisp\n" "(define stdout (current-output-port))\n" "(define p (make-soft-port\n" " (vector\n" @@ -179,9 +184,10 @@ SCM_DEFINE (scm_make_soft_port, "make-soft-port", 2, 0, 0, " (lambda () (display \".\" stdout))\n" " (lambda () (char-upcase (read-char)))\n" " (lambda () (display \"@@\" stdout)))\n" - " \"rw\"))\n\n" + " \"rw\"))\n" + "\n" "(write p p) @result{} #<input-output: soft 8081e20>\n" - "@end example") + "@end lisp") #define FUNC_NAME s_scm_make_soft_port { scm_port *pt; diff --git a/libguile/weaks.c b/libguile/weaks.c index c6cf591bb..81a4b879f 100644 --- a/libguile/weaks.c +++ b/libguile/weaks.c @@ -56,17 +56,18 @@ SCM_DEFINE (scm_make_weak_vector, "make-weak-vector", 1, 1, 0, - (SCM k, SCM fill), + (SCM size, SCM fill), "Return a weak vector with @var{size} elements. If the optional\n" - "argument @var{fill} is given, all entries in the vector will be set to\n" - "@var{fill}. The default value for @var{fill} is the empty list.") + "argument @var{fill} is given, all entries in the vector will be\n" + "set to @var{fill}. The default value for @var{fill} is the\n" + "empty list.") #define FUNC_NAME s_scm_make_weak_vector { /* Dirk:FIXME:: We should probably rather use a double cell for weak vectors. */ SCM v; - v = scm_make_vector (scm_sum (k, SCM_MAKINUM (2)), fill); + v = scm_make_vector (scm_sum (size, SCM_MAKINUM (2)), fill); SCM_DEFER_INTS; - SCM_SET_VECTOR_LENGTH (v, SCM_INUM (k), scm_tc7_wvect); + SCM_SET_VECTOR_LENGTH (v, SCM_INUM (size), scm_tc7_wvect); SCM_SETVELTS(v, SCM_VELTS(v) + 2); SCM_VELTS(v)[-2] = SCM_EOL; SCM_UNPACK (SCM_VELTS (v)[-1]) = 0; @@ -81,10 +82,10 @@ SCM_REGISTER_PROC(s_list_to_weak_vector, "list->weak-vector", 1, 0, 0, scm_weak_ SCM_DEFINE (scm_weak_vector, "weak-vector", 0, 0, 1, (SCM l), "@deffnx primitive list->weak-vector l\n" - "Construct a weak vector from a list: @code{weak-vector} uses the list of\n" - "its arguments while @code{list->weak-vector} uses its only argument\n" - "@var{l} (a list) to construct a weak vector the same way\n" - "@code{vector->list} would.") + "Construct a weak vector from a list: @code{weak-vector} uses\n" + "the list of its arguments while @code{list->weak-vector} uses\n" + "its only argument @var{l} (a list) to construct a weak vector\n" + "the same way @code{list->vector} would.") #define FUNC_NAME s_scm_weak_vector { SCM res; @@ -110,12 +111,12 @@ SCM_DEFINE (scm_weak_vector, "weak-vector", 0, 0, 1, SCM_DEFINE (scm_weak_vector_p, "weak-vector?", 1, 0, 0, - (SCM x), + (SCM obj), "Return @code{#t} if @var{obj} is a weak vector. Note that all\n" "weak hashes are also weak vectors.") #define FUNC_NAME s_scm_weak_vector_p { - return SCM_BOOL(SCM_WVECTP (x) && !SCM_IS_WHVEC (x)); + return SCM_BOOL(SCM_WVECTP (obj) && !SCM_IS_WHVEC (obj)); } #undef FUNC_NAME @@ -126,18 +127,20 @@ SCM_DEFINE (scm_weak_vector_p, "weak-vector?", 1, 0, 0, SCM_DEFINE (scm_make_weak_key_hash_table, "make-weak-key-hash-table", 1, 0, 0, - (SCM k), + (SCM size), "@deffnx primitive make-weak-value-hash-table size\n" "@deffnx primitive make-doubly-weak-hash-table size\n" - "Return a weak hash table with @var{size} buckets. As with any hash\n" - "table, choosing a good size for the table requires some caution.\n\n" - "You can modify weak hash tables in exactly the same way you would modify\n" - "regular hash tables. (@pxref{Hash Tables})") + "Return a weak hash table with @var{size} buckets. As with any\n" + "hash table, choosing a good size for the table requires some\n" + "caution.\n" + "\n" + "You can modify weak hash tables in exactly the same way you\n" + "would modify regular hash tables. (@pxref{Hash Tables})") #define FUNC_NAME s_scm_make_weak_key_hash_table { SCM v; - SCM_VALIDATE_INUM (1,k); - v = scm_make_weak_vector (k, SCM_EOL); + SCM_VALIDATE_INUM (1, size); + v = scm_make_weak_vector (size, SCM_EOL); SCM_DEFER_INTS; SCM_UNPACK (SCM_VELTS (v)[-1]) = 1; SCM_ALLOW_INTS; @@ -147,14 +150,14 @@ 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), + (SCM size), "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; - SCM_VALIDATE_INUM (1,k); - v = scm_make_weak_vector (k, SCM_EOL); + SCM_VALIDATE_INUM (1, size); + v = scm_make_weak_vector (size, SCM_EOL); SCM_DEFER_INTS; SCM_UNPACK (SCM_VELTS (v)[-1]) = 2; SCM_ALLOW_INTS; @@ -165,14 +168,14 @@ 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), + (SCM size), "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; - SCM_VALIDATE_INUM (1,k); - v = scm_make_weak_vector (k, SCM_EOL); + SCM_VALIDATE_INUM (1, size); + v = scm_make_weak_vector (size, SCM_EOL); SCM_DEFER_INTS; SCM_UNPACK (SCM_VELTS (v)[-1]) = 3; SCM_ALLOW_INTS; @@ -181,7 +184,7 @@ SCM_DEFINE (scm_make_doubly_weak_hash_table, "make-doubly-weak-hash-table", 1, 0 #undef FUNC_NAME SCM_DEFINE (scm_weak_key_hash_table_p, "weak-key-hash-table?", 1, 0, 0, - (SCM x), + (SCM obj), "@deffnx primitive weak-value-hash-table? obj\n" "@deffnx primitive doubly-weak-hash-table? obj\n" "Return @code{#t} if @var{obj} is the specified weak hash\n" @@ -189,27 +192,27 @@ SCM_DEFINE (scm_weak_key_hash_table_p, "weak-key-hash-table?", 1, 0, 0, "nor a weak value hash table.") #define FUNC_NAME s_scm_weak_key_hash_table_p { - return SCM_BOOL(SCM_WVECTP (x) && SCM_IS_WHVEC(x)); + return SCM_BOOL(SCM_WVECTP (obj) && SCM_IS_WHVEC(obj)); } #undef FUNC_NAME SCM_DEFINE (scm_weak_value_hash_table_p, "weak-value-hash-table?", 1, 0, 0, - (SCM x), - "Return @code{#t} if @var{x} is a weak value hash table.") + (SCM obj), + "Return @code{#t} if @var{obj} 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)); + return SCM_BOOL(SCM_WVECTP (obj) && SCM_IS_WHVEC_V(obj)); } #undef FUNC_NAME SCM_DEFINE (scm_doubly_weak_hash_table_p, "doubly-weak-hash-table?", 1, 0, 0, - (SCM x), - "Return @code{#t} if @var{x} is a doubly weak hash table.") + (SCM obj), + "Return @code{#t} if @var{obj} 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)); + return SCM_BOOL(SCM_WVECTP (obj) && SCM_IS_WHVEC_B (obj)); } #undef FUNC_NAME |