From 2016628e8e20b64dbd9b980b8d11084e11c7cc3a Mon Sep 17 00:00:00 2001
From: Vincent Sanders <vince@kyllikki.org>
Date: Sun, 19 Apr 2015 12:57:09 +0100
Subject: [PATCH] Improve bitmap operation table interface documentation.

---
 image/bitmap.h | 68 +++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 56 insertions(+), 12 deletions(-)

diff --git a/image/bitmap.h b/image/bitmap.h
index 459a50a73..b121f8abd 100644
--- a/image/bitmap.h
+++ b/image/bitmap.h
@@ -16,17 +16,18 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \file
- * Generic bitmap handling (interface).
+/**
+ * \file
+ * Generic bitmap handling interface.
  *
  * This interface wraps the native platform-specific image format, so that
  * portable image convertors can be written.
  *
  * Bitmaps are required to be 32bpp with components in the order RR GG BB AA.
- * 
- * For example, an opaque 1x1 pixel image would yield the following bitmap 
+ *
+ * For example, an opaque 1x1 pixel image would yield the following bitmap
  * data:
- * 
+ *
  * Red  : 0xff 0x00 0x00 0x00
  * Green: 0x00 0xff 0x00 0x00
  * Blue : 0x00 0x00 0xff 0x00
@@ -54,9 +55,9 @@
 #define _NETSURF_IMAGE_BITMAP_H_
 
 #define BITMAP_NEW		0
-#define BITMAP_OPAQUE		(1 << 0)	/** image is opaque */
-#define BITMAP_MODIFIED		(1 << 1)	/** buffer has been modified */
-#define BITMAP_CLEAR_MEMORY	(1 << 2)	/** memory should be wiped */
+#define BITMAP_OPAQUE		(1 << 0) /**< image is opaque */
+#define BITMAP_MODIFIED		(1 << 1) /**< buffer has been modified */
+#define BITMAP_CLEAR_MEMORY	(1 << 2) /**< memory should be wiped */
 
 struct content;
 struct bitmap;
@@ -68,55 +69,98 @@ struct gui_bitmap_table {
 	/* Mandantory entries */
 
 	/**
-	 * Create a new bitmap
+	 * Create a new bitmap.
+	 *
+	 * \param width width of image in pixels
+	 * \param height width of image in pixels
+	 * \param state The state to create the bitmap in.
+	 * \return A bitmap structure or NULL on error.
 	 */
 	void *(*create)(int width, int height, unsigned int state);
 
 	/**
-	 * Destroy a bitmap
+	 * Destroy a bitmap.
+	 *
+	 * \param bitmap The bitmap to destroy.
 	 */
 	void (*destroy)(void *bitmap);
 
 	/**
-	 * Set the opacity of a bitmap
+	 * Set the opacity of a bitmap.
+	 *
+	 * \param bitmap The bitmap to set opacity on.
+	 * \param opaque The bitmap opacity to set.
 	 */
 	void (*set_opaque)(void *bitmap, bool opaque);
 
 	/**
-	 * Get the opacity of a bitmap
+	 * Get the opacity of a bitmap.
+	 *
+	 * \param bitmap The bitmap to examine.
+	 * \return The bitmap opacity.
 	 */
 	bool (*get_opaque)(void *bitmap);
 
 	/**
+	 * Test if a bitmap is opaque.
+	 *
+	 * \param bitmap The bitmap to examine.
+	 * \return The bitmap opacity.
 	 */
 	bool (*test_opaque)(void *bitmap);
 
 	/**
+	 * Get the image buffer from a bitmap
+	 *
+	 * \param bitmap The bitmap to get the buffer from.
+	 * \return The image buffer or NULL if there is none.
 	 */
 	unsigned char *(*get_buffer)(void *bitmap);
 
 	/**
+	 * Get the number of bytes per row of the image
+	 *
+	 * \param bitmap The bitmap
+	 * \return The number of bytes for a row of the bitmap.
 	 */
 	size_t (*get_rowstride)(void *bitmap);
 
 	/**
+	 * Get the bitmap width
+	 *
+	 * \param bitmap The bitmap
+	 * \return The bitmap width in pixels.
 	 */
 	int (*get_width)(void *bitmap);
 
 	/**
+	 * Get the bitmap height
+	 *
+	 * \param bitmap The bitmap
+	 * \return The bitmap height in pixels.
 	 */
 	int (*get_height)(void *bitmap);
 
 	/**
+	 * The the *bytes* per pixel.
+	 *
+	 * \param bitmap The bitmap
 	 */
 	size_t (*get_bpp)(void *bitmap);
 
 	/**
+	 * Savde a bitmap to disc.
+	 *
+	 * \param bitmap The bitmap to save
+	 * \param path The path to save the bitmap to.
+	 * \param flags Flags affectin the save.
 	 */
 	bool (*save)(void *bitmap, const char *path, unsigned flags);
 
 	/**
 	 * Marks a bitmap as modified.
+	 *
+	 * \param bitmap The bitmap set as modified.
 	 */
 	void (*modified)(void *bitmap);
 };