From 560cde70416e5f9df8d44ecfea6ec3b8f33c2928 Mon Sep 17 00:00:00 2001
From: Thomas Bernard <miniupnp@free.fr>
Date: Fri, 13 Jul 2018 08:36:05 +0200
Subject: [PATCH] improve doxygen comments of gfx2surface.h

---
 src/gfx2surface.h | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/src/gfx2surface.h b/src/gfx2surface.h
index 72801d19..0af271ff 100644
--- a/src/gfx2surface.h
+++ b/src/gfx2surface.h
@@ -31,16 +31,41 @@
 /// to load 256 color pictures into memory
 typedef struct
 {
-  byte * pixels;
-  T_Palette palette;
-  word w;           ///< Width
-  word h;           ///< Height
+  byte * pixels;      ///< pixel data (1 byte = 1 pixel)
+  T_Palette palette;  ///< 256 color palette
+  word w;             ///< Width
+  word h;             ///< Height
 } T_GFX2_Surface;
 
+/**
+ * Allocate a new surface.
+ * @param width, height dimension of the new surface. Cannot be 0
+ * @return the new surface
+ * @return NULL in case of error
+ */
 T_GFX2_Surface * New_GFX2_Surface(word width, word height);
+
+/**
+ * Free the surface object and the associated pixel data.
+ * @param surface The surface to free
+ */
 void Free_GFX2_Surface(T_GFX2_Surface * surface);
 
+/**
+ * Retrieve a pixel value.
+ * @param surface The surface to access
+ * @param x, y the coordinate of the pixel to read
+ * @return the pixel 8 bits value
+ * @return 0 for out of bound access
+ */
 byte Get_GFX2_Surface_pixel(const T_GFX2_Surface * surface, int x, int y);
+
+/**
+ * Set a pixel. Nothing is done if the coordinates are out of bound.
+ * @param surface The surface to access
+ * @param x, y the coordinate of the pixel to write
+ * @param value the 8 bits pixel value
+ */
 void Set_GFX2_Surface_pixel(T_GFX2_Surface * surface, int x, int y, byte value);
 
 #endif