[pdf-devel] Regarding API consistency

[gerel]

Hey all,

I have been working on a small perl script to check the consistency between the
API documented on the reference manual and what is actually implemented. I'm
using it and seems pretty useful.  I'll put it on the "build-aux" directory so
you can also use it if you like.

Here is an example (you can call it with "-h" for help):
##
~/PROJECTS/libgnupdf/build-aux $ ./check-api-doc-consistency.pl -f | grep -v 
"pdf_time\|fsys\|matrix"
pdf_alloc() ... failed
pdf_realloc() ... failed
pdf_i64_add() ... failed
pdf_list_create() ... failed
pdf_text_new_from_pdf_string() ... failed
pdf_text_new_from_unicode() ... failed
pdf_text_new_from_u32() ... failed
pdf_text_empty_p() ... failed
pdfo_create_real() ... failed
pdfo_get_real() ... failed
pdfo_set_real() ... failed

--- Failed 59 of 137 ---
###

Dispite there are 59 cases failing only those which I show there (with "grep
-v") are implemented (time procedures, fsys, etc are not yet implemented).

BTW, pdfo_*() seems to have been discarded since I found the procedure
"pdf_set_real()" on the sources. We should fix that.

Here I send patches to fix the rest of the consistency cases.
###
Index: doc/gnupdf.texi
===================================================================
RCS file: /sources/pdf/libgnupdf/doc/gnupdf.texi,v
retrieving revision 1.52
diff -u -r1.52 gnupdf.texi
--- doc/gnupdf.texi     6 May 2008 18:53:43 -0000       1.52
+++ doc/gnupdf.texi     8 May 2008 17:19:34 -0000
@@ -281,7 +281,7 @@
 allocation and deallocation. The usual malloc/free/realloc schema is
 used to provide this service.
 
address@hidden void* pdf_alloc (const size_t @var{size})
address@hidden void* pdf_alloc (const pdf_size_t @var{size})
 
 Allocates heap memory.
 
@@ -335,7 +335,7 @@
 @end table
 @end deftypefun
 
address@hidden void* pdf_realloc (void address@hidden, const int @var{size})
address@hidden void* pdf_realloc (void address@hidden, const pdf_size_t 
@var{size})
 
 Reallocates memory.
 
@@ -580,16 +580,16 @@
 @end table
 @end deftypefun
 
address@hidden pdf_status_t pdf_i64_add (pdf_i64_t address@hidden, const 
pdf_i64_t @var{addend_1}, const pdf_i64_t @var{addend_2})
address@hidden pdf_status_t pdf_i64_add (pdf_i64_t address@hidden, const 
pdf_i64_t @var{addend1}, const pdf_i64_t @var{addend2})
 
 Adds two 64 bit numbers
 
 @table @strong
 @item Parameters
 @table @var
address@hidden addend_1
address@hidden addend1
 First addend of the sum
address@hidden addend_2
address@hidden addend2
 Second addend of the sum
 @item dest
 Where 64 bit result is stored
@@ -1293,7 +1293,7 @@
 @node Creating and Destroying Lists
 @subsection Creating and Destroying Lists
 
address@hidden pdf_status_t pdf_list_create (pdf_list_element_equals_fn_t 
@var{equals_fn}, pdf_list_element_dipose_fn_t @var{dispose_fn}, const 
pdf_bool_t @var{allow_duplicates}, pdf_list_t @var{*list})
address@hidden pdf_status_t pdf_list_create (pdf_list_element_equals_fn_t 
@var{equals_fn}, pdf_list_element_dispose_fn_t @var{dispose_fn}, const 
pdf_bool_t @var{allow_duplicates}, pdf_list_t @var{*list})
 
 Create a new list containing no elements.
 
@@ -2621,7 +2621,7 @@
 @end table
 @end deftypefun
 
address@hidden pdf_status_t pdf_text_new_from_pdf_string (pdf_text_t 
address@hidden, const pdf_char_t address@hidden, const pdf_size_t @var{size}, 
pdf_char_t address@hidden, pdf_size_t address@hidden)
address@hidden pdf_status_t pdf_text_new_from_pdf_string (pdf_text_t 
address@hidden, const pdf_char_t address@hidden, const pdf_size_t @var{size}, 
pdf_char_t address@hidden, pdf_size_t address@hidden)
 
 Create a new text object and initialize it with a given `PDF string'
 text representation. This `PDF string' can be either encoded in UTF-16BE, with
@@ -2682,7 +2682,7 @@
 @end table
 @end deftypefun
 
address@hidden pdf_status_t pdf_text_new_from_unicode (pdf_text_t 
address@hidden, const pdf_char_t address@hidden, const pdf_size_t @var{size}, 
const enum pdf_text_unicode_encoding_e @var{enc})
address@hidden pdf_status_t pdf_text_new_from_unicode (pdf_text_t 
address@hidden, const pdf_char_t address@hidden, const pdf_size_t @var{size}, 
const enum pdf_text_unicode_encoding_e @var{enc})
 
 Create a new text object from a string of Unicode characters in a
 given unicode encoding. The Unicode string can be given with or without BOM,
@@ -2698,7 +2698,7 @@
 @table @var
 @item text
 A pointer to the newly created text object.
address@hidden ucs
address@hidden str
 A Unicode string.
 @item size
 The length of @var{ucs} in bytes.
@@ -2871,7 +2871,7 @@
 @end table
 @end deftypefun
 
address@hidden {inline pdf_bool_t} pdf_text_empty_p (const pdf_text_t 
@var{text})
address@hidden pdf_bool_t pdf_text_empty_p (const pdf_text_t @var{text})
 
 Determine if a given text variable is empty (contains no text).
 
Index: src/base/pdf-alloc.c
===================================================================
RCS file: /sources/pdf/libgnupdf/src/base/pdf-alloc.c,v
retrieving revision 1.3
diff -u -r1.3 pdf-alloc.c
--- src/base/pdf-alloc.c        6 May 2008 18:53:44 -0000       1.3
+++ src/base/pdf-alloc.c        8 May 2008 17:19:34 -0000
@@ -1,4 +1,4 @@
-/* -*- mode: C -*- Time-stamp: "2008-05-06 14:25:15 gerel"
+/* -*- mode: C -*- Time-stamp: "2008-05-08 13:49:00 gerel"
  *
  *       File:         pdf-alloc.c
  *       Date:         Fri Feb 22 21:05:05 2008
@@ -53,7 +53,7 @@
 }
 
 inline void *
-pdf_realloc (void *pointer, pdf_size_t size)
+pdf_realloc (void *pointer, const pdf_size_t size)
 {
   pointer = realloc (pointer, size);
   if (!pointer && size != 0)
Index: src/base/pdf-alloc.h
===================================================================
RCS file: /sources/pdf/libgnupdf/src/base/pdf-alloc.h,v
retrieving revision 1.3
diff -u -r1.3 pdf-alloc.h
--- src/base/pdf-alloc.h        6 May 2008 18:53:44 -0000       1.3
+++ src/base/pdf-alloc.h        8 May 2008 17:19:34 -0000
@@ -1,4 +1,4 @@
-/* -*- mode: C -*- Time-stamp: "2008-05-06 14:25:11 gerel"
+/* -*- mode: C -*- Time-stamp: "2008-05-08 13:48:21 gerel"
  *
  *       File:         pdf-alloc.h
  *       Date:         Fri Feb 22 20:54:18 2008
@@ -36,7 +36,7 @@
 
 void *pdf_alloc (const pdf_size_t size);
 void pdf_dealloc (void *pointer);
-void *pdf_realloc (void *pointer, pdf_size_t size);
+void *pdf_realloc (void *pointer, const pdf_size_t size);
 
 /* END PUBLIC */
 
Index: src/base/pdf-text.c
===================================================================
RCS file: /sources/pdf/libgnupdf/src/base/pdf-text.c,v
retrieving revision 1.13
diff -u -r1.13 pdf-text.c
--- src/base/pdf-text.c 6 May 2008 18:53:45 -0000       1.13
+++ src/base/pdf-text.c 8 May 2008 17:19:36 -0000
@@ -426,7 +426,7 @@
 
 pdf_status_t
 pdf_text_new_from_u32 (pdf_text_t *text,
-                       pdf_u32_t number)
+                       const pdf_u32_t number)
 {
   /* Longest number to hold in 32bit: 2^32 = 4294967296 (10 chars) */
   pdf_char_t temp[10];

###


cheers

-gerel