[gegl] add quick doc to explain what does classes in gegl/buffer/

[Michael Murà <mmure src gnome org>]

commit 9afd12e6735f7b32a9a9b03024427b7ffeb9e50f
Author: Michael Murà <batolettre gmail com>
Date:   Sat Jul 23 13:03:53 2011 +0200

    add quick doc to explain what does classes in gegl/buffer/

 gegl/buffer/gegl-tile-backend-file.h    |    4 ++++
 gegl/buffer/gegl-tile-backend-ram.h     |    4 ++++
 gegl/buffer/gegl-tile-backend-tiledir.h |    4 ++++
 gegl/buffer/gegl-tile-backend.h         |    7 ++++++-
 gegl/buffer/gegl-tile-handler-cache.h   |    4 ++++
 gegl/buffer/gegl-tile-handler-chain.h   |   10 +++++++---
 gegl/buffer/gegl-tile-handler-empty.h   |    6 ++++++
 gegl/buffer/gegl-tile-handler-log.h     |    4 ++++
 gegl/buffer/gegl-tile-handler-zoom.h    |    4 ++++
 gegl/buffer/gegl-tile-handler.h         |   11 ++++++++++-
 gegl/buffer/gegl-tile-source.h          |    8 +++++++-
 gegl/buffer/gegl-tile-storage.h         |    5 +++++
 12 files changed, 65 insertions(+), 6 deletions(-)
---
diff --git a/gegl/buffer/gegl-tile-backend-file.h b/gegl/buffer/gegl-tile-backend-file.h
index 968dc08..018503c 100644
--- a/gegl/buffer/gegl-tile-backend-file.h
+++ b/gegl/buffer/gegl-tile-backend-file.h
@@ -21,6 +21,10 @@
 
 #include "gegl-tile-backend.h"
 
+/***
+ * GeglTileBackendFile is a GeglTileBackend that store tiles in a unique file.
+ */
+
 G_BEGIN_DECLS
 
 #define GEGL_TYPE_TILE_BACKEND_FILE            (gegl_tile_backend_file_get_type ())
diff --git a/gegl/buffer/gegl-tile-backend-ram.h b/gegl/buffer/gegl-tile-backend-ram.h
index 8d496ba..e58c02b 100644
--- a/gegl/buffer/gegl-tile-backend-ram.h
+++ b/gegl/buffer/gegl-tile-backend-ram.h
@@ -21,6 +21,10 @@
 
 #include "gegl-tile-backend.h"
 
+/***
+ * GeglTileBackendRam is a GeglTileBackend that store tiles in RAM.
+ */
+
 G_BEGIN_DECLS
 
 #define GEGL_TYPE_TILE_BACKEND_RAM            (gegl_tile_backend_ram_get_type ())
diff --git a/gegl/buffer/gegl-tile-backend-tiledir.h b/gegl/buffer/gegl-tile-backend-tiledir.h
index 0e4245f..67aa770 100644
--- a/gegl/buffer/gegl-tile-backend-tiledir.h
+++ b/gegl/buffer/gegl-tile-backend-tiledir.h
@@ -22,6 +22,10 @@
 #include "gegl-tile-backend.h"
 #include <gio/gio.h>
 
+/***
+ * GeglTileBackendTileDir is a GeglTileBackend that store tiles as a set of files in a directory.
+ */
+
 G_BEGIN_DECLS
 
 #define GEGL_TYPE_TILE_BACKEND_TILE_DIR            (gegl_tile_backend_tiledir_get_type ())
diff --git a/gegl/buffer/gegl-tile-backend.h b/gegl/buffer/gegl-tile-backend.h
index 8c1ad89..8e9fb35 100644
--- a/gegl/buffer/gegl-tile-backend.h
+++ b/gegl/buffer/gegl-tile-backend.h
@@ -21,6 +21,11 @@
 
 #include "gegl-tile-source.h"
 
+/***
+ * GeglTileBackend is a simple basic GeglTileSource that provide and store tiles. This classe is
+ * generic and is specialized in subclasses for different kind of storage.
+ */
+
 G_BEGIN_DECLS
 
 #define GEGL_TYPE_TILE_BACKEND            (gegl_tile_backend_get_type ())
@@ -28,7 +33,7 @@ G_BEGIN_DECLS
 #define GEGL_TILE_BACKEND_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_TILE_BACKEND, GeglTileBackendClass))
 #define GEGL_IS_TILE_BACKEND(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GEGL_TYPE_TILE_BACKEND))
 #define GEGL_IS_TILE_BACKEND_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),  GEGL_TYPE_TILE_BACKEND))
-#define GEGL_TILE_BACKEND_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj),  GEGL_TYPE_TILE_BACKEND, GeglTileBackendClass))
+#define GEGL_TILE_BACKEND_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),  GEGL_TYPE_TILE_BACKEND, GeglTileBackendClass))
 
 struct _GeglTileBackend
 {
diff --git a/gegl/buffer/gegl-tile-handler-cache.h b/gegl/buffer/gegl-tile-handler-cache.h
index f81bd00..d421121 100644
--- a/gegl/buffer/gegl-tile-handler-cache.h
+++ b/gegl/buffer/gegl-tile-handler-cache.h
@@ -21,6 +21,10 @@
 
 #include "gegl-tile-handler.h"
 
+/***
+ * GeglTileHandlerCache is a GeglTileHandler that cache recently used tiles in memory.
+ */
+
 #define GEGL_TYPE_TILE_HANDLER_CACHE            (gegl_tile_handler_cache_get_type ())
 #define GEGL_TILE_HANDLER_CACHE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GEGL_TYPE_TILE_HANDLER_CACHE, GeglTileHandlerCache))
 #define GEGL_TILE_HANDLER_CACHE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_TILE_HANDLER_CACHE, GeglTileHandlerCacheClass))
diff --git a/gegl/buffer/gegl-tile-handler-chain.h b/gegl/buffer/gegl-tile-handler-chain.h
index 342a040..17beaf8 100644
--- a/gegl/buffer/gegl-tile-handler-chain.h
+++ b/gegl/buffer/gegl-tile-handler-chain.h
@@ -21,12 +21,16 @@
 
 #include "gegl-tile-handler.h"
 
+/***
+ * GeglTileHandlerChain is a GeglTileHandler that easily create and destroy a chain of GeglTileHandler.
+ */
+
 #define GEGL_TYPE_TILE_HANDLER_CHAIN            (gegl_tile_handler_chain_get_type ())
-#define GEGL_TILE_HANDLER_CHAIN(obj)               (G_TYPE_CHECK_INSTANCE_CAST ((obj), GEGL_TYPE_TILE_HANDLER_CHAIN, GeglTileHandlerChain))
-#define GEGL_TILE_HANDLER_CHAIN_CLASS(klass)       (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_TILE_HANDLER_CHAIN, GeglTileHandlerChainClass))
+#define GEGL_TILE_HANDLER_CHAIN(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GEGL_TYPE_TILE_HANDLER_CHAIN, GeglTileHandlerChain))
+#define GEGL_TILE_HANDLER_CHAIN_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_TILE_HANDLER_CHAIN, GeglTileHandlerChainClass))
 #define GEGL_IS_TILE_HANDLER_CHAIN(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GEGL_TYPE_TILE_HANDLER_CHAIN))
 #define GEGL_IS_TILE_HANDLER_CHAIN_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),  GEGL_TYPE_TILE_HANDLER_CHAIN))
-#define GEGL_TILE_HANDLER_CHAIN_GET_CLASS(obj)     (G_TYPE_INSTANCE_GET_CLASS ((obj),  GEGL_TYPE_TILE_HANDLER_CHAIN, GeglTileHandlerChainClass))
+#define GEGL_TILE_HANDLER_CHAIN_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),  GEGL_TYPE_TILE_HANDLER_CHAIN, GeglTileHandlerChainClass))
 
 struct _GeglTileHandlerChain
 {
diff --git a/gegl/buffer/gegl-tile-handler-empty.h b/gegl/buffer/gegl-tile-handler-empty.h
index d8b3c97..db66eb1 100644
--- a/gegl/buffer/gegl-tile-handler-empty.h
+++ b/gegl/buffer/gegl-tile-handler-empty.h
@@ -22,6 +22,12 @@
 #include "gegl-tile-handler.h"
 #include "gegl-tile-handler-cache.h"
 
+/***
+ * GeglTileHandlerEmpty is a GeglTileHandler that create COW tiles sharing data
+ * with a single empty tile if the tile is not provided by the handlers/sources
+ * lower down.
+ */
+
 G_BEGIN_DECLS
 
 #define GEGL_TYPE_TILE_HANDLER_EMPTY            (gegl_tile_handler_empty_get_type ())
diff --git a/gegl/buffer/gegl-tile-handler-log.h b/gegl/buffer/gegl-tile-handler-log.h
index 26aecdc..8b69a6e 100644
--- a/gegl/buffer/gegl-tile-handler-log.h
+++ b/gegl/buffer/gegl-tile-handler-log.h
@@ -21,6 +21,10 @@
 
 #include "gegl-tile-handler.h"
 
+/***
+ * GeglTileHandlerLog is a GeglTileHandler which print commands that are passed through it.
+ */
+
 G_BEGIN_DECLS
 
 #define GEGL_TYPE_TILE_HANDLER_LOG            (gegl_tile_handler_log_get_type ())
diff --git a/gegl/buffer/gegl-tile-handler-zoom.h b/gegl/buffer/gegl-tile-handler-zoom.h
index a4e1ff4..749f6e1 100644
--- a/gegl/buffer/gegl-tile-handler-zoom.h
+++ b/gegl/buffer/gegl-tile-handler-zoom.h
@@ -22,6 +22,10 @@
 #include "gegl-tile-handler.h"
 #include "gegl-tile-handler-cache.h"
 
+/***
+ * GeglTileHandlerZoom is a GeglTileHandler that handle the mipmapping process.
+ */
+
 G_BEGIN_DECLS
 
 #define GEGL_TYPE_TILE_HANDLER_ZOOM            (gegl_tile_handler_zoom_get_type ())
diff --git a/gegl/buffer/gegl-tile-handler.h b/gegl/buffer/gegl-tile-handler.h
index 9fcfaba..2d60e9c 100644
--- a/gegl/buffer/gegl-tile-handler.h
+++ b/gegl/buffer/gegl-tile-handler.h
@@ -21,9 +21,18 @@
 
 #include "gegl-tile-source.h"
 
+/***
+ * GeglTileHandler define the chain pattern that allow to stack GeglTileSource classes on
+ * top of each others, each doing different task in response to command given (see GeglTileSource).
+ *
+ * A classical GeglBuffer is a stack of subclasses of GeglTileHandler with a GeglTileBackend on
+ * the bottom. This architecture is designed to be modular and flexible on purpose, even allowing
+ * to use a GeglBuffer as a source for another GeglBuffer.
+ */
+
 G_BEGIN_DECLS
 
-#define GEGL_TYPE_TILE_HANDLER       (gegl_tile_handler_get_type ())
+#define GEGL_TYPE_TILE_HANDLER            (gegl_tile_handler_get_type ())
 #define GEGL_TILE_HANDLER(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GEGL_TYPE_TILE_HANDLER, GeglTileHandler))
 #define GEGL_TILE_HANDLER_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_TILE_HANDLER, GeglTileHandlerClass))
 #define GEGL_IS_TILE_HANDLER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GEGL_TYPE_TILE_HANDLER))
diff --git a/gegl/buffer/gegl-tile-source.h b/gegl/buffer/gegl-tile-source.h
index f5d1397..2dd6d86 100644
--- a/gegl/buffer/gegl-tile-source.h
+++ b/gegl/buffer/gegl-tile-source.h
@@ -23,6 +23,12 @@
 #include <babl/babl.h>
 #include "gegl-tile.h"
 
+/***
+ * GeglTileSource is the very top classes of the tile/buffer handling of Gegl. It defines the generic
+ * command mechanism to interact with a set of tiles. This classe is derived in GeglTileBackend and
+ * GeglTileHandler.
+ */
+
 G_BEGIN_DECLS
 
 #define GEGL_TYPE_TILE_SOURCE            (gegl_tile_source_get_type ())
@@ -186,7 +192,7 @@ gboolean  gegl_tile_source_idle      (GeglTileSource *source);
 #endif
 
 #define gegl_tile_source_command(source,cmd,x,y,z,tile)\
-(((GeglTileSource*)(source))->command(source,cmd,x,y,z,tile))
+   (((GeglTileSource*)(source))->command(source,cmd,x,y,z,tile))
 
 #define gegl_tile_source_set_tile(source,x,y,z,tile) \
    (gboolean)GPOINTER_TO_INT(gegl_tile_source_command(source,GEGL_TILE_SET,x,y,z,tile))
diff --git a/gegl/buffer/gegl-tile-storage.h b/gegl/buffer/gegl-tile-storage.h
index 6d48e3f..aa38c7c 100644
--- a/gegl/buffer/gegl-tile-storage.h
+++ b/gegl/buffer/gegl-tile-storage.h
@@ -22,6 +22,11 @@
 #include "gegl-tile-handler-chain.h"
 #include "gegl-tile-handler-cache.h"
 
+/***
+ * GeglTileStorage provide the command API to GeglBuffer, and setup a chain of GeglTileHandler to
+ * treat and store tiles.
+ */
+
 #define GEGL_TYPE_TILE_STORAGE            (gegl_tile_storage_get_type ())
 #define GEGL_TILE_STORAGE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GEGL_TYPE_TILE_STORAGE, GeglTileStorage))
 #define GEGL_TILE_STORAGE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_TILE_STORAGE, GeglTileStorageClass))