Add some more docs to fitz.h

Add docs for fz_store, fz_image, fz_halftones.

Move fz_item definition into res_store.c as it does not need to be
external.

Rename fz_store_context to fz_keep_store_context to be consistent.

3 files changed, 162 insertions, 22 deletions

diff --git a/fitz/base_context.c b/fitz/base_context.c
index d1ce63ae..2eeb6683 100644
--- a/fitz/base_context.c
+++ b/fitz/base_context.c
@@ -122,7 +122,7 @@ fz_clone_context_internal(fz_context *ctx)
 	if (ctx == NULL || ctx->alloc == NULL)
 		return NULL;
 	new_ctx = new_context_phase1(ctx->alloc, ctx->locks);
-	new_ctx->store = fz_store_keep(ctx);
+	new_ctx->store = fz_keep_store_context(ctx);
 	new_ctx->glyph_cache = fz_keep_glyph_cache(ctx);
 	new_ctx->font = fz_keep_font_context(ctx);
 	return new_ctx;
diff --git a/fitz/fitz.h b/fitz/fitz.h
index f72aecb9..594bc4e9 100644
--- a/fitz/fitz.h
+++ b/fitz/fitz.h
@@ -936,13 +936,28 @@ void fz_grow_buffer(fz_context *ctx, fz_buffer *buf);
 void fz_trim_buffer(fz_context *ctx, fz_buffer *buf);
 
 /*
- * Resource store
+	Resource store
+
+	MuPDF stores decoded "objects" into a store for potential reuse.
+	If the size of the store gets too big, objects stored within it can
+	be evicted and freed to recover space. When MuPDF comes to decode
+	such an object, it will check to see if a version of this object is
+	already in the store - if it is, it will simply reuse it. If not, it
+	will decode it and place it into the store.
+
+	All objects that can be placed into the store are derived from the
+	fz_storable type (i.e. this should be the first component of the
+	objects structure). This allows for consistent (thread safe)
+	reference counting, and includes a function that will be called to
+	free the object as soon as the reference count reaches zero.
+
+	Most objects offer fz_keep_XXXX/fz_drop_XXXX functions derived
+	from fz_keep_storable/fz_drop_storable. Creation of such objects
+	includes a call to FZ_INIT_STORABLE to set up the fz_storable header.
  */
 
 typedef struct fz_storable_s fz_storable;
 
-typedef struct fz_item_s fz_item;
-
 typedef void (fz_store_free_fn)(fz_context *, fz_storable *);
 
 struct fz_storable_s {
@@ -955,6 +970,9 @@ struct fz_storable_s {
 	S->free = (FREE); \
 	} while (0)
 
+void *fz_keep_storable(fz_context *, fz_storable *);
+void fz_drop_storable(fz_context *, fz_storable *);
+
 /*
 	Specifies the maximum size in bytes of the resource store in
 	fz_context. Given as argument to fz_new_context.
@@ -969,6 +987,22 @@ enum {
 	FZ_STORE_DEFAULT = 256 << 20,
 };
 
+/*
+	The store can be seen as a dictionary that maps keys to fz_storable
+	values. In order to allow keys of different types to be stored, we
+	have a structure full of functions for each key 'type'; this
+	fz_store_type pointer is stored with each key, and tells the store
+	how to perform certain operations (like taking/dropping a reference,
+	comparing two keys, outputting details for debugging etc).
+
+	The store uses a hash table internally for speed where possible. In
+	order for this to work, we need a mechanism for turning a generic
+	'key' into 'a hashable string'. For this purpose the type structure
+	contains a make_hash_key function pointer that maps from a void *
+	to an fz_store_hash structure. If make_hash_key function returns 0,
+	then the key is determined not to be hashable, and the value is
+	not stored in the hash table.
+*/
 typedef struct fz_store_hash_s fz_store_hash;
 
 struct fz_store_hash_s
@@ -1000,18 +1034,95 @@ struct fz_store_type_s
 	void (*debug)(void *);
 };
 
+/*
+	fz_store_new_context: Create a new store inside the context
+
+	max: The maximum size (in bytes) that the store is allowed to grow
+	to. FZ_STORE_UNLIMITED means no limit.
+*/
 void fz_new_store_context(fz_context *ctx, unsigned int max);
+
+/*
+	fz_drop_store_context: Drop a reference to the store.
+*/
 void fz_drop_store_context(fz_context *ctx);
-fz_store *fz_store_keep(fz_context *ctx);
+
+/*
+	fz_keep_store_context: Take a reference to the store.
+*/
+fz_store *fz_keep_store_context(fz_context *ctx);
+
+/*
+	fz_debug_store: Dump the contents of the store for debugging.
+*/
 void fz_debug_store(fz_context *ctx);
 
-void *fz_keep_storable(fz_context *, fz_storable *);
-void fz_drop_storable(fz_context *, fz_storable *);
+/*
+	fz_store_item: Add an item to the store.
+
+	Add an item into the store, returning NULL for success. If an item
+	with the same key is found in the store, then our item will not be
+	inserted, and the function will return a pointer to that value
+	instead. This function takes its own reference to val, as required
+	(i.e. the caller maintains ownership of its own reference).
 
+	key: The key to use to index the item.
+
+	val: The value to store.
+
+	itemsize: The size in bytes of the value (as counted towards the
+	store size).
+
+	type: Functions used to manipulate the key.
+*/
 void *fz_store_item(fz_context *ctx, void *key, void *val, unsigned int itemsize, fz_store_type *type);
+
+/*
+	fz_find_item: Find an item within the store.
+
+	free: The function used to free the value (to ensure we get a value
+	of the correct type).
+
+	key: The key to use to index the item.
+
+	type: Functions used to manipulate the key.
+
+	Returns NULL for not found, otherwise returns a pointer to the value
+	indexed by key to which a reference has been taken.
+*/
 void *fz_find_item(fz_context *ctx, fz_store_free_fn *free, void *key, fz_store_type *type);
+
+/*
+	fz_remove_item: Remove an item from the store.
+
+	If an item indexed by the given key exists in the store, remove it.
+
+	free: The function used to free the value (to ensure we get a value
+	of the correct type).
+
+	key: The key to use to find the item to remove.
+
+	type: Functions used to manipulate the key.
+*/
 void fz_remove_item(fz_context *ctx, fz_store_free_fn *free, void *key, fz_store_type *type);
+
+/*
+	fz_empty_store: Evict everything from the store.
+*/
 void fz_empty_store(fz_context *ctx);
+
+/*
+	fz_store_scavenge: Internal function used as part of the scavenging
+	allocator; when we fail to allocate memory, before returning a
+	failure to the caller, we try to scavenge space within the store by
+	evicting at least 'size' bytes. The allocator then retries.
+
+	size: The number of bytes we are trying to have free.
+
+	phase: What phase of the scavenge we are in. Updated on exit.
+
+	Returns non zero if we managed to free any memory.
+*/
 int fz_store_scavenge(fz_context *ctx, unsigned int size, int *phase);
 
 /*
@@ -1340,10 +1451,10 @@ void fz_write_pam(fz_context *ctx, fz_pixmap *pixmap, char *filename, int saveal
 void fz_write_png(fz_context *ctx, fz_pixmap *pixmap, char *filename, int savealpha);
 
 /*
- * Images are either a reference to a pixmap, or details of how to make
- * a pixmap. To know how to make a pixmap we need a block of compressed
- * data (typically a stream decoded all the way until the image filter)
- * and then the details of the params for the filter to do the final step.
+	Images are storable objects from which we can obtain fz_pixmaps.
+	These may be implemented as simple wrappers around a pixmap, or as
+	more complex things that decode at different subsample settings on
+	demand.
  */
 typedef struct fz_image_s fz_image;
 
@@ -1356,8 +1467,37 @@ struct fz_image_s
 	fz_pixmap *(*get_pixmap)(fz_context *, fz_image *, int w, int h);
 };
 
-fz_pixmap *fz_image_to_pixmap(fz_context *, fz_image *, int w, int h);
+/*
+	fz_image_to_pixmap: Called to get a handle to a pixmap from an image.
+
+	image: The image to retrieve a pixmap from.
+
+	w: The desired width (in pixels). This may be completely ignored, but
+	may serve as an indication of a suitable subsample factor to use for
+	image types that support this.
+
+	h: The desired height (in pixels). This may be completely ignored, but
+	may serve as an indication of a suitable subsample factor to use for
+	image types that support this.
+
+	Returns a non NULL pixmap pointer. May throw exceptions.
+*/
+fz_pixmap *fz_image_to_pixmap(fz_context *ctx, fz_image *image, int w, int h);
+
+/*
+	fz_drop_image: Drop a reference to an image.
+
+	image: The image to drop a reference to.
+*/
 void fz_drop_image(fz_context *ctx, fz_image *image);
+
+/*
+	fz_keep_image: Increment the reference count of an image.
+
+	image: The image to take a reference to.
+
+	Returns a pointer to the image.
+*/
 fz_image *fz_keep_image(fz_context *ctx, fz_image *image);
 
 fz_pixmap *fz_load_jpx(fz_context *ctx, unsigned char *data, int size, fz_colorspace *cs);
@@ -1366,11 +1506,10 @@ fz_pixmap *fz_load_png(fz_context *doc, unsigned char *data, int size);
 fz_pixmap *fz_load_tiff(fz_context *doc, unsigned char *data, int size);
 
 /*
- * Bitmaps have 1 bit per component. Only used for creating halftoned versions
- * of contone buffers, and saving out. Samples are stored msb first, akin to
- * pbms.
- */
-
+	Bitmaps have 1 bit per component. Only used for creating halftoned
+	versions of contone buffers, and saving out. Samples are stored msb
+	first, akin to pbms.
+*/
 typedef struct fz_bitmap_s fz_bitmap;
 
 struct fz_bitmap_s
@@ -1388,10 +1527,9 @@ void fz_drop_bitmap(fz_context *ctx, fz_bitmap *bit);
 void fz_write_pbm(fz_context *ctx, fz_bitmap *bitmap, char *filename);
 
 /*
- * A halftone is a set of threshold tiles, one per component. Each threshold
- * tile is a pixmap, possibly of varying sizes and phases.
- */
-
+	A halftone is a set of threshold tiles, one per component. Each
+	threshold tile is a pixmap, possibly of varying sizes and phases.
+*/
 typedef struct fz_halftone_s fz_halftone;
 
 struct fz_halftone_s
diff --git a/fitz/res_store.c b/fitz/res_store.c
index 0e3e7214..2a7680e3 100644
--- a/fitz/res_store.c
+++ b/fitz/res_store.c
@@ -1,5 +1,7 @@
 #include "fitz.h"
 
+typedef struct fz_item_s fz_item;
+
 struct fz_item_s
 {
 	void *key;
@@ -420,7 +422,7 @@ fz_empty_store(fz_context *ctx)
 }
 
 fz_store *
-fz_store_keep(fz_context *ctx)
+fz_keep_store_context(fz_context *ctx)
 {
 	if (ctx == NULL || ctx->store == NULL)
 		return NULL;