API improvements.

Add missing API comments.

Move private definitions to implementation headers or C files.

Move internal functions to implementation headers.

5 files changed, 78 insertions, 17 deletions

diff --git a/include/mupdf/fitz/annotation.h b/include/mupdf/fitz/annotation.h
index 9864fd16..79df092d 100644
--- a/include/mupdf/fitz/annotation.h
+++ b/include/mupdf/fitz/annotation.h
@@ -11,7 +11,15 @@
 */
 void *fz_new_annot(fz_context *ctx, int size);
 
+/*
+	fz_keep_annot: Take a new reference to an annotation.
+*/
 fz_annot *fz_keep_annot(fz_context *ctx, fz_annot *annot);
+
+/*
+	fz_drop_annot: Drop a reference to an annotation. If the
+	reference count reaches zero, annot will be destroyed.
+*/
 void fz_drop_annot(fz_context *ctx, fz_annot *annot);
 
 /*
diff --git a/include/mupdf/fitz/bitmap.h b/include/mupdf/fitz/bitmap.h
index 3b35b543..353f4ccc 100644
--- a/include/mupdf/fitz/bitmap.h
+++ b/include/mupdf/fitz/bitmap.h
@@ -44,7 +44,7 @@ typedef struct fz_halftone_s fz_halftone;
 	fz_new_bitmap_from_pixmap: Make a bitmap from a pixmap and a halftone.
 
 	pix: The pixmap to generate from. Currently must be a single color
-	component + alpha (where the alpha is assumed to be solid).
+	component with no alpha.
 
 	ht: The halftone to use. NULL implies the default halftone.
 
@@ -53,7 +53,23 @@ typedef struct fz_halftone_s fz_halftone;
 */
 fz_bitmap *fz_new_bitmap_from_pixmap(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht);
 
-fz_bitmap *fz_new_bitmap_from_pixmap_band(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht, int band_start, int band_height);
+/*
+	fz_new_bitmap_from_pixmap_band: Make a bitmap from a pixmap and a
+	halftone, allowing for the position of the pixmap within an
+	overall banded rendering.
+
+	pix: The pixmap to generate from. Currently must be a single color
+	component with no alpha.
+
+	ht: The halftone to use. NULL implies the default halftone.
+
+	band_start: Vertical offset within the overall banded rendering
+	(in pixels)
+
+	Returns the resultant bitmap. Throws exceptions in the case of
+	failure to allocate.
+*/
+fz_bitmap *fz_new_bitmap_from_pixmap_band(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht, int band_start);
 
 struct fz_bitmap_s
 {
@@ -63,20 +79,41 @@ struct fz_bitmap_s
 	unsigned char *samples;
 };
 
+/*
+	fz_new_bitmap: Create a new bitmap.
+
+	w, h: Width and Height for the bitmap
+
+	n: Number of color components (assumed to be a divisor of 8)
+
+	xres, yres: X and Y resolutions (in pixels per inch).
+
+	Returns pointer to created bitmap structure. The bitmap
+	data is uninitialised.
+*/
 fz_bitmap *fz_new_bitmap(fz_context *ctx, int w, int h, int n, int xres, int yres);
 
-void fz_bitmap_details(fz_bitmap *bitmap, int *w, int *h, int *n, int *stride);
+/*
+	fz_bitmap_details: Retrieve details of a given bitmap.
 
-void fz_clear_bitmap(fz_context *ctx, fz_bitmap *bit);
+	bitmap: The bitmap to query.
 
-struct fz_halftone_s
-{
-	int refs;
-	int n;
-	fz_pixmap *comp[1];
-};
+	w: Pointer to storage to retrieve width (or NULL).
+
+	h: Pointer to storage to retrieve height (or NULL).
+
+	n: Pointer to storage to retrieve number of color components (or NULL).
+
+	stride: Pointer to storage to retrieve bitmap stride (or NULL).
+*/
+void fz_bitmap_details(fz_bitmap *bitmap, int *w, int *h, int *n, int *stride);
 
-fz_halftone *fz_new_halftone(fz_context *ctx, int num_comps);
+/*
+	fz_clear_bitmap: Clear a previously created bitmap.
+
+	bit: The bitmap to clear.
+*/
+void fz_clear_bitmap(fz_context *ctx, fz_bitmap *bit);
 
 /*
 	fz_default_halftone: Create a 'default' halftone structure
@@ -90,7 +127,16 @@ fz_halftone *fz_new_halftone(fz_context *ctx, int num_comps);
 */
 fz_halftone *fz_default_halftone(fz_context *ctx, int num_comps);
 
-void fz_drop_halftone(fz_context *ctx, fz_halftone *half);
+/*
+	fz_keep_halftone: Take an additional reference to a
+	halftone.
+*/
 fz_halftone *fz_keep_halftone(fz_context *ctx, fz_halftone *half);
 
+/*
+	fz_drop_halftone: Drop a reference to a halftone. If the
+	reference count reaches zero, ht will be destroyed.
+*/
+void fz_drop_halftone(fz_context *ctx, fz_halftone *ht);
+
 #endif
diff --git a/source/fitz/halftone.c b/source/fitz/halftone.c
index dd9bb58f..1a4da0f0 100644
--- a/source/fitz/halftone.c
+++ b/source/fitz/halftone.c
@@ -1,6 +1,13 @@
 #include "mupdf/fitz.h"
 
-fz_halftone *
+struct fz_halftone_s
+{
+	int refs;
+	int n;
+	fz_pixmap *comp[1];
+};
+
+static fz_halftone *
 fz_new_halftone(fz_context *ctx, int comps)
 {
 	fz_halftone *ht;
@@ -490,7 +497,7 @@ static void do_threshold_4(const unsigned char * restrict ht_line, const unsigne
 
 fz_bitmap *fz_new_bitmap_from_pixmap(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht)
 {
-	return fz_new_bitmap_from_pixmap_band(ctx, pix, ht, 0, 0);
+	return fz_new_bitmap_from_pixmap_band(ctx, pix, ht, 0);
 }
 
 /* TAOCP, vol 2, p337 */
@@ -509,7 +516,7 @@ static int gcd(int u, int v)
 	while (1);
 }
 
-fz_bitmap *fz_new_bitmap_from_pixmap_band(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht, int band_start, int band_height)
+fz_bitmap *fz_new_bitmap_from_pixmap_band(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht, int band_start)
 {
 	fz_bitmap *out = NULL;
 	unsigned char *ht_line = NULL;
diff --git a/source/tools/mudraw.c b/source/tools/mudraw.c
index c9908906..470ff66d 100644
--- a/source/tools/mudraw.c
+++ b/source/tools/mudraw.c
@@ -575,7 +575,7 @@ static void drawband(fz_context *ctx, fz_page *page, fz_display_list *list, cons
 			fz_unmultiply_pixmap(ctx, pix);
 
 		if ((output_format == OUT_PCL && out_cs == CS_MONO) || (output_format == OUT_PBM) || (output_format == OUT_PKM))
-			*bit = fz_new_bitmap_from_pixmap_band(ctx, pix, NULL, band_start, band_height);
+			*bit = fz_new_bitmap_from_pixmap_band(ctx, pix, NULL, band_start);
 	}
 	fz_catch(ctx)
 	{
diff --git a/source/tools/muraster.c b/source/tools/muraster.c
index f08de504..ddb546b1 100644
--- a/source/tools/muraster.c
+++ b/source/tools/muraster.c
@@ -722,7 +722,7 @@ static int drawband(fz_context *ctx, fz_page *page, fz_display_list *list, const
 		dev = NULL;
 
 		if ((output_format == OUT_PBM) || (output_format == OUT_PKM))
-			*bit = fz_new_bitmap_from_pixmap_band(ctx, pix, NULL, band_start, band_height);
+			*bit = fz_new_bitmap_from_pixmap_band(ctx, pix, NULL, band_start);
 	}
 	fz_catch(ctx)
 	{