Re: [pdf-devel] Task #7792: Design of the Error Module

[gerel]

Here is the patch:

Index: gnupdf.texi
===================================================================
RCS file: /sources/pdf/libgnupdf/doc/gnupdf.texi,v
retrieving revision 1.26
diff -u -r1.26 gnupdf.texi
--- gnupdf.texi 20 Feb 2008 10:49:55 -0000      1.26
+++ gnupdf.texi 22 Feb 2008 15:13:57 -0000
@@ -103,6 +103,163 @@
 @section Error Management
 
 
+The Error module will provide procedures for error reporting to the
+client as well as for error tracing (via debug messages) to
+developers. Here we also define status types returned by most
+procedures (there are exceptions though).
+
address@hidden
+* Status types::
+* Error Reporting procedures::
+* Debugging procedures::
address@hidden menu
+
address@hidden Status types
address@hidden Status types
+
address@hidden {Data Type} pdf_status_t
+A status variable.
address@hidden deftp
+
+The following constants defines the valid values to be hold in a
address@hidden variable:
+
address@hidden {Constant} PDF_OK
+Success
address@hidden deftp
+
address@hidden {Constant} PDF_ERROR
+A serious error
address@hidden deftp
+
address@hidden {Constant} PDF_EBADDATA
+Invalid or bad arguments
address@hidden deftp
+
address@hidden {Constant} PDF_ENOMEM
+Insufficient memory
address@hidden deftp
+
address@hidden {Constant} PDF_EEOF
+End of file
address@hidden deftp
+
address@hidden {Constant} PDF_EDIVBYZERO
+Divison by zero
address@hidden deftp
+
address@hidden {Constant} PDF_ENONODE
+No node found
address@hidden deftp
+
address@hidden {Constant} PDF_EINVRANGE
+Invalid range
address@hidden deftp
+
address@hidden {Constant} PDF_ETEXTENC
+Error in text encoding
address@hidden deftp
+
address@hidden {Constant} PDF_ENOMATCH 
+No matching found
address@hidden deftp
+
+This list will grow as we get closer to a mature state of development.
+
+
address@hidden Error Reporting procedures
address@hidden Error Reporting procedures
+
address@hidden void pdf_perror (pdf_status_t @var{status}, const char 
address@hidden)
+
+Prints the message corresponding to @var{status} to stderr followed by 
@var{str}.
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden status
+status code
address@hidden str
+a user-defined message
address@hidden table
address@hidden Returns
+nothing
address@hidden Usage example
address@hidden
+pdf_status_t st;
+
+st = pdf_i64_add (dest, addend_1, addend_2);
+
+if (st != PDF_OK)
address@hidden
+        pdf_perror (st, "Couldn't do i64 addition");
address@hidden
address@hidden example
address@hidden table
address@hidden deftypefun
+
address@hidden void pdf_error (pdf_status_t @var{status}, FILE address@hidden, 
const char address@hidden, @var{...})
+
+Prints a message with `fprintf (@var{fd}, @var{format}, ...)'; 
+if @var{status} is nonzero, also prints the corresponding message.
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden status
+status code
address@hidden fd
+file descriptor open for writing
address@hidden format
+string format for the message
address@hidden ...
+format's arguments
address@hidden table
address@hidden Returns
+nothing
address@hidden Usage example
address@hidden
+pdf_status_t st;
+
+st = pdf_i64_add (dest, addend_1, addend_2);
+
+if (st != PDF_OK)
address@hidden
+        pdf_error (st, logfd, "Couldn't do i64 addition");
address@hidden
address@hidden example
address@hidden table
address@hidden deftypefun
+
address@hidden Debugging procedures
address@hidden Debugging procedures
+
+For each layer there is a macro procedure defined. The file name and
+the line number at which the error ocurred is printed to stderr
+followed by @var{message}.
+
address@hidden PDF_DEBUG_BASE (message, ...)
address@hidden defmac
address@hidden PDF_DEBUG_OBJECT (message, ...)
address@hidden defmac
address@hidden PDF_DEBUG_DOCUMENT (message, ...)
address@hidden defmac
address@hidden PDF_DEBUG_PAGE (message, ...)
address@hidden defmac
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden message
+a 'const char*' string
address@hidden ...
+message's arguments
address@hidden table
address@hidden Usage example
address@hidden
+PDF_DEBUG_BASE("Testing macro '%s' '%d' '%lf'", "string", 7, 10.1);
address@hidden example
address@hidden table
 
 @node Memory Allocation
 @section Memory Allocation
@@ -224,7 +381,6 @@
 
 @menu
 * Boolean Types::
-* Status Types::
 * Numeric Types::
 * Big Numbers::
 @end menu
@@ -237,7 +393,7 @@
 @end deftp
 
 The following constants defines the valid values to be hold in a
address@hidden variable:
address@hidden variable:
 
 @deftp {Constant} PDF_TRUE
 Logical true.
@@ -247,24 +403,6 @@
 Logical false.
 @end deftp
 
address@hidden Status Types
address@hidden Status Types
-
address@hidden {Data Type} pdf_status_t
-A status value.
address@hidden deftp
-
-The following constants defines the valid values to be hold in a
address@hidden variable:
-
address@hidden {Constant} PDF_OK
-A success status.
address@hidden deftp
-
address@hidden {Constant} PDF_ERROR
-An error status.
address@hidden deftp
-
 @node Numeric Types
 @subsection Numeric Types

###

Review it and I'll commit.

-gerel