diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 01c0512421..6855613f4e 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -108,11 +108,12 @@ typedef struct SDL_SurfaceData SDL_SurfaceData;
  */
 typedef struct SDL_Surface
 {
-    SDL_SurfaceFlags flags;     /**< Read-only */
-    SDL_PixelFormat format;     /**< Read-only */
-    int w, h;                   /**< Read-only */
-    int pitch;                  /**< Read-only */
-    void *pixels;               /**< Read-only pointer, writable pixels if non-NULL */
+    SDL_SurfaceFlags flags;     /**< The flags of the surface, read-only */
+    SDL_PixelFormat format;     /**< The format of the surface, read-only */
+    int w;                      /**< The width of the surface, read-only. */
+    int h;                      /**< The height of the surface, read-only. */
+    int pitch;                  /**< The distance in bytes between rows of pixels, read-only */
+    void *pixels;               /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */
 
     int refcount;               /**< Application reference count, used when freeing surface */