Subject: bug#10521: closed (Re: bug#10521: Patch: Improve consistency of definitions of C functions in manual.)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 03 Feb 2012 19:29:07 +0000

Your bug report

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

which was filed against the guile package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
10521: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=10521
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#10521: Patch: Improve consistency of definitions of C functions in manual.
From: Andy Wingo <[email-masked]>
To: [email-masked]
Cc: [email-masked]
Date: Fri, 03 Feb 2012 14:17:02 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

On Mon 16 Jan 2012 04:54, Bake Timmons <[email-masked]> 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/

Subject: Patch: Improve consistency of definitions of C functions in manual.
From: Bake Timmons <[email-masked]>
To: [email-masked]
Date: Sun, 15 Jan 2012 22:54:33 -0500
List-Id: <debbugs-submit.debbugs.gnu.org>

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.

>From 0c3ee0770bb50d464661d25b5ca6d40f920c7cb8 Mon Sep 17 00:00:00 2001
From: Bake Timmons <[email-masked]>
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