bug#10521: Patch: Improve consistency of definitions of C functions in manual.

bug#10521: Patch: Improve consistency of definitions of C functions in manual.

[Bake Timmons]

[-- Attachment #1: Type: text/plain, Size: 192 bytes --]

Attached is a patch to improve the consistency of definitions of C
functions in the manual.  It adds missing parentheses and commas and
fixes a untyped definition that should be a typed one.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Improve consistency of definitions of C functions in manual. --]
[-- Type: text/x-diff, Size: 14198 bytes --]

From 0c3ee0770bb50d464661d25b5ca6d40f920c7cb8 Mon Sep 17 00:00:00 2001
From: Bake Timmons <b3timmons@speedymail.org>
Date: Sun, 15 Jan 2012 22:18:08 -0500
Subject: [PATCH] Improve consistency of definitions of C functions in manual.

* doc/ref/api-compound.texi
* doc/ref/api-evaluation.texi
* doc/ref/api-foreign.texi
* doc/ref/api-io.texi
* doc/ref/posix.texi
* doc/ref/srfi-modules.texi: Add missing parentheses and commas to definitions
  of C functions.

* doc/ref/api-data.texi: Change from @deffn to @deftypefn for C function
  with arguments not of SCM type.
---
 doc/ref/api-compound.texi   |    6 ++--
 doc/ref/api-data.texi       |   12 +++---
 doc/ref/api-evaluation.texi |    2 +-
 doc/ref/api-foreign.texi    |   12 +++---
 doc/ref/api-io.texi         |    2 +-
 doc/ref/posix.texi          |    4 +-
 doc/ref/srfi-modules.texi   |   76 +++++++++++++++++++++---------------------
 7 files changed, 57 insertions(+), 57 deletions(-)

diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index bc997a3..6fc5b2e 100644
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -777,7 +777,7 @@ in the vector.
 
 @rnindex vector-length
 @deffn {Scheme Procedure} vector-length vector
-@deffnx {C Function} scm_vector_length vector
+@deffnx {C Function} scm_vector_length (vector)
 Return the number of elements in @var{vector} as an exact integer.
 @end deffn
 
@@ -787,7 +787,7 @@ Return the number of elements in @var{vec} as a @code{size_t}.
 
 @rnindex vector-ref
 @deffn {Scheme Procedure} vector-ref vec k
-@deffnx {C Function} scm_vector_ref vec k
+@deffnx {C Function} scm_vector_ref (vec, k)
 Return the contents of position @var{k} of @var{vec}.
 @var{k} must be a valid index of @var{vec}.
 @lisp
@@ -816,7 +816,7 @@ error.
 
 @rnindex vector-set!
 @deffn {Scheme Procedure} vector-set! vec k obj
-@deffnx {C Function} scm_vector_set_x vec k obj
+@deffnx {C Function} scm_vector_set_x (vec, k, obj)
 Store @var{obj} in position @var{k} of @var{vec}.
 @var{k} must be a valid index of @var{vec}.
 The value returned by @samp{vector-set!} is unspecified.
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 4fc582e..9891d85 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -5266,15 +5266,15 @@ When you want to do more from C, you should convert between symbols
 and strings using @code{scm_symbol_to_string} and
 @code{scm_string_to_symbol} and work with the strings.
 
-@deffn {C Function} scm_from_latin1_symbol (const char *name)
-@deffnx {C Function} scm_from_utf8_symbol (const char *name)
+@deftypefn {C Function} scm_from_latin1_symbol (const char *name)
+@deftypefnx {C Function} scm_from_utf8_symbol (const char *name)
 Construct and return a Scheme symbol whose name is specified by the
 null-terminated C string @var{name}.  These are appropriate when
 the C string is hard-coded in the source code.
-@end deffn
+@end deftypefn
 
-@deffn {C Function} scm_from_locale_symbol (const char *name)
-@deffnx {C Function} scm_from_locale_symboln (const char *name, size_t len)
+@deftypefn {C Function} scm_from_locale_symbol (const char *name)
+@deftypefnx {C Function} scm_from_locale_symboln (const char *name, size_t len)
 Construct and return a Scheme symbol whose name is specified by
 @var{name}.  For @code{scm_from_locale_symbol}, @var{name} must be null
 terminated; for @code{scm_from_locale_symboln} the length of @var{name} is
@@ -5284,7 +5284,7 @@ Note that these functions should @emph{not} be used when @var{name} is a
 C string constant, because there is no guarantee that the current locale
 will match that of the source code.  In such cases, use
 @code{scm_from_latin1_symbol} or @code{scm_from_utf8_symbol}.
-@end deffn
+@end deftypefn
 
 @deftypefn  {C Function} SCM scm_take_locale_symbol (char *str)
 @deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len)
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 2f59de8..9fffb87 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -904,7 +904,7 @@ by @code{file-encoding}, if any, again by using
 @code{set-port-encoding!}.  Then the code can be read as normal.
 
 @deffn {Scheme Procedure} file-encoding port
-@deffnx {C Function} scm_file_encoding port
+@deffnx {C Function} scm_file_encoding (port)
 Scan the port for an Emacs-like character coding declaration near the
 top of the contents of a port with random-accessible contents
 (@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs,
diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi
index 82925e6..da926f4 100644
--- a/doc/ref/api-foreign.texi
+++ b/doc/ref/api-foreign.texi
@@ -540,7 +540,7 @@ A value returned by @code{dynamic-pointer} is a Scheme wrapper for a C
 pointer.
 
 @deffn {Scheme Procedure} pointer-address pointer
-@deffnx {C Function} scm_pointer_address pointer
+@deffnx {C Function} scm_pointer_address (pointer)
 Return the numerical value of @var{pointer}.
 
 @example
@@ -594,7 +594,7 @@ module contains procedures that can be used to convert byte sequences to
 Scheme objects such as strings, floating point numbers, or integers.
 
 @deffn {Scheme Procedure} pointer->bytevector pointer len [offset [uvec_type]]
-@deffnx {C Function} scm_foreign_to_bytevector pointer len offset uvec_type
+@deffnx {C Function} scm_foreign_to_bytevector (pointer, len, offset, uvec_type)
 Return a bytevector aliasing the @var{len} bytes pointed to by
 @var{pointer}.
 
@@ -614,7 +614,7 @@ Mutating the returned bytevector mutates the memory pointed to by
 @end deffn
 
 @deffn {Scheme Procedure} bytevector->pointer bv [offset]
-@deffnx {C Function} scm_bytevector_to_pointer bv offset
+@deffnx {C Function} scm_bytevector_to_pointer (bv, offset)
 Return a pointer pointer aliasing the memory pointed to by @var{bv} or
 @var{offset} bytes after @var{bv} when @var{offset} is passed.
 @end deffn
@@ -740,7 +740,7 @@ its type, offset, and alignment. Guile has some primitives to support
 this.
 
 @deffn {Scheme Procedure} sizeof type
-@deffnx {C Function} scm_sizeof type
+@deffnx {C Function} scm_sizeof (type)
 Return the size of @var{type}, in bytes.
 
 @var{type} should be a valid C type, like @code{int}.
@@ -751,7 +751,7 @@ also be a list of types, in which case the size of a
 @end deffn
 
 @deffn {Scheme Procedure} alignof type
-@deffnx {C Function} scm_alignof type
+@deffnx {C Function} scm_alignof (type)
 Return the alignment of @var{type}, in bytes.
 
 @var{type} should be a valid C type, like @code{int}.
@@ -801,7 +801,7 @@ Of course, the land of C is not all nouns and no verbs: there are
 functions too, and Guile allows you to call them.
 
 @deffn {Scheme Procedure} pointer->procedure return_type func_ptr arg_types
-@deffnx {C Procedure} scm_pointer_to_procedure return_type func_ptr arg_types
+@deffnx {C Procedure} scm_pointer_to_procedure (return_type, func_ptr, arg_types)
 Make a foreign function.
 
 Given the foreign void pointer @var{func_ptr}, its argument and
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 9b52766..24c2706 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -129,7 +129,7 @@ this fluid otherwise.
 @end defvr
 
 @deffn {Scheme Procedure} port-encoding port
-@deffnx {C Function} scm_port_encoding
+@deffnx {C Function} scm_port_encoding (port)
 Returns, as a string, the character encoding that @var{port} uses to interpret
 its input and output.  The value @code{#f} is equivalent to @code{"ISO-8859-1"}.
 @end deffn
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index d8e8bb6..2e8da4b 100644
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -953,7 +953,7 @@ which is usual for ordinary file creation,
 @end deffn
 
 @deffn {Scheme Procedure} tmpfile
-@deffnx {C Function} scm_tmpfile
+@deffnx {C Function} scm_tmpfile ()
 Return an input/output port to a unique temporary file
 named using the path prefix @code{P_tmpdir} defined in
 @file{stdio.h}.
@@ -2841,7 +2841,7 @@ created with,
 @deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port
 @deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
 @deffnx {Scheme Procedure} make-socket-address AF_UNIX path
-@deffnx {C Function} scm_make_socket_address family address arglist
+@deffnx {C Function} scm_make_socket_address (family, address, arglist)
 Return a new socket address object.  The first argument is the address
 family, one of the @code{AF} constants, then the arguments vary
 according to the family.
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index 02681de..d00fbc4 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -1463,18 +1463,18 @@ indicated type.
 @deffnx {Scheme Procedure} make-f64vector n [value]
 @deffnx {Scheme Procedure} make-c32vector n [value]
 @deffnx {Scheme Procedure} make-c64vector n [value]
-@deffnx {C Function} scm_make_u8vector n [value]
-@deffnx {C Function} scm_make_s8vector n [value]
-@deffnx {C Function} scm_make_u16vector n [value]
-@deffnx {C Function} scm_make_s16vector n [value]
-@deffnx {C Function} scm_make_u32vector n [value]
-@deffnx {C Function} scm_make_s32vector n [value]
-@deffnx {C Function} scm_make_u64vector n [value]
-@deffnx {C Function} scm_make_s64vector n [value]
-@deffnx {C Function} scm_make_f32vector n [value]
-@deffnx {C Function} scm_make_f64vector n [value]
-@deffnx {C Function} scm_make_c32vector n [value]
-@deffnx {C Function} scm_make_c64vector n [value]
+@deffnx {C Function} scm_make_u8vector (n, value)
+@deffnx {C Function} scm_make_s8vector (n, value)
+@deffnx {C Function} scm_make_u16vector (n, value)
+@deffnx {C Function} scm_make_s16vector (n, value)
+@deffnx {C Function} scm_make_u32vector (n, value)
+@deffnx {C Function} scm_make_s32vector (n, value)
+@deffnx {C Function} scm_make_u64vector (n, value)
+@deffnx {C Function} scm_make_s64vector (n, value)
+@deffnx {C Function} scm_make_f32vector (n, value)
+@deffnx {C Function} scm_make_f64vector (n, value)
+@deffnx {C Function} scm_make_c32vector (n, value)
+@deffnx {C Function} scm_make_c64vector (n, value)
 Return a newly allocated homogeneous numeric vector holding @var{n}
 elements of the indicated type.  If @var{value} is given, the vector
 is initialized with that value, otherwise the contents are
@@ -1549,18 +1549,18 @@ Return the number of elements in @var{vec}.
 @deffnx {Scheme Procedure} f64vector-ref vec i
 @deffnx {Scheme Procedure} c32vector-ref vec i
 @deffnx {Scheme Procedure} c64vector-ref vec i
-@deffnx {C Function} scm_u8vector_ref (vec i)
-@deffnx {C Function} scm_s8vector_ref (vec i)
-@deffnx {C Function} scm_u16vector_ref (vec i)
-@deffnx {C Function} scm_s16vector_ref (vec i)
-@deffnx {C Function} scm_u32vector_ref (vec i)
-@deffnx {C Function} scm_s32vector_ref (vec i)
-@deffnx {C Function} scm_u64vector_ref (vec i)
-@deffnx {C Function} scm_s64vector_ref (vec i)
-@deffnx {C Function} scm_f32vector_ref (vec i)
-@deffnx {C Function} scm_f64vector_ref (vec i)
-@deffnx {C Function} scm_c32vector_ref (vec i)
-@deffnx {C Function} scm_c64vector_ref (vec i)
+@deffnx {C Function} scm_u8vector_ref (vec, i)
+@deffnx {C Function} scm_s8vector_ref (vec, i)
+@deffnx {C Function} scm_u16vector_ref (vec, i)
+@deffnx {C Function} scm_s16vector_ref (vec, i)
+@deffnx {C Function} scm_u32vector_ref (vec, i)
+@deffnx {C Function} scm_s32vector_ref (vec, i)
+@deffnx {C Function} scm_u64vector_ref (vec, i)
+@deffnx {C Function} scm_s64vector_ref (vec, i)
+@deffnx {C Function} scm_f32vector_ref (vec, i)
+@deffnx {C Function} scm_f64vector_ref (vec, i)
+@deffnx {C Function} scm_c32vector_ref (vec, i)
+@deffnx {C Function} scm_c64vector_ref (vec, i)
 Return the element at index @var{i} in @var{vec}.  The first element
 in @var{vec} is index 0.
 @end deffn
@@ -1577,18 +1577,18 @@ in @var{vec} is index 0.
 @deffnx {Scheme Procedure} f64vector-set! vec i value
 @deffnx {Scheme Procedure} c32vector-set! vec i value
 @deffnx {Scheme Procedure} c64vector-set! vec i value
-@deffnx {C Function} scm_u8vector_set_x (vec i value)
-@deffnx {C Function} scm_s8vector_set_x (vec i value)
-@deffnx {C Function} scm_u16vector_set_x (vec i value)
-@deffnx {C Function} scm_s16vector_set_x (vec i value)
-@deffnx {C Function} scm_u32vector_set_x (vec i value)
-@deffnx {C Function} scm_s32vector_set_x (vec i value)
-@deffnx {C Function} scm_u64vector_set_x (vec i value)
-@deffnx {C Function} scm_s64vector_set_x (vec i value)
-@deffnx {C Function} scm_f32vector_set_x (vec i value)
-@deffnx {C Function} scm_f64vector_set_x (vec i value)
-@deffnx {C Function} scm_c32vector_set_x (vec i value)
-@deffnx {C Function} scm_c64vector_set_x (vec i value)
+@deffnx {C Function} scm_u8vector_set_x (vec, i, value)
+@deffnx {C Function} scm_s8vector_set_x (vec, i, value)
+@deffnx {C Function} scm_u16vector_set_x (vec, i, value)
+@deffnx {C Function} scm_s16vector_set_x (vec, i, value)
+@deffnx {C Function} scm_u32vector_set_x (vec, i, value)
+@deffnx {C Function} scm_s32vector_set_x (vec, i, value)
+@deffnx {C Function} scm_u64vector_set_x (vec, i, value)
+@deffnx {C Function} scm_s64vector_set_x (vec, i, value)
+@deffnx {C Function} scm_f32vector_set_x (vec, i, value)
+@deffnx {C Function} scm_f64vector_set_x (vec, i, value)
+@deffnx {C Function} scm_c32vector_set_x (vec, i, value)
+@deffnx {C Function} scm_c64vector_set_x (vec, i, value)
 Set the element at index @var{i} in @var{vec} to @var{value}.  The
 first element in @var{vec} is index 0.  The return value is
 unspecified.
@@ -1736,13 +1736,13 @@ Return the number of elements in @var{vec}.
 @end deffn
 
 @deffn  {Scheme Procedure} uniform-vector-ref vec i
-@deffnx {C Function} scm_uniform_vector_ref (vec i)
+@deffnx {C Function} scm_uniform_vector_ref (vec, i)
 Return the element at index @var{i} in @var{vec}.  The first element
 in @var{vec} is index 0.
 @end deffn
 
 @deffn  {Scheme Procedure} uniform-vector-set! vec i value
-@deffnx {C Function} scm_uniform_vector_set_x (vec i value)
+@deffnx {C Function} scm_uniform_vector_set_x (vec, i, value)
 Set the element at index @var{i} in @var{vec} to @var{value}.  The
 first element in @var{vec} is index 0.  The return value is
 unspecified.
-- 
1.7.8.3

bug#10521: Patch: Improve consistency of definitions of C functions in manual.

[Andy Wingo]

On Mon 16 Jan 2012 04:54, Bake Timmons <b3timmons@speedymail.org> writes:

> Attached is a patch to improve the consistency of definitions of C
> functions in the manual.  It adds missing parentheses and commas and
> fixes a untyped definition that should be a typed one.

Applied, thanks!

Andy
-- 
http://wingolog.org/