From 2350dbbd574b6f38ec43854684aa3a867c0b74b8 Mon Sep 17 00:00:00 2001
From: Larpon <Larpon@users.noreply.github.com>
Date: Tue, 5 Apr 2022 12:21:03 +0200
Subject: [PATCH] gg: add missing doc strings to pub fns in image.* (#13934)

---
 vlib/gg/image.c.v | 22 +++++++++++++++++++++-
 vlib/gg/image.v   | 15 +++++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/vlib/gg/image.c.v b/vlib/gg/image.c.v
index e1492e2f69..a2cf3e01cf 100644
--- a/vlib/gg/image.c.v
+++ b/vlib/gg/image.c.v
@@ -7,6 +7,8 @@ import stbi
 import sokol.gfx
 import sokol.sgl
 
+// Image holds the fileds and data needed to
+// represent a bitmap/pixel based image in memory.
 [heap]
 pub struct Image {
 pub mut:
@@ -22,6 +24,7 @@ pub mut:
 	path        string
 }
 
+// create_image creates an `Image` from `file`.
 // TODO return ?Image
 pub fn (mut ctx Context) create_image(file string) Image {
 	// println('\ncreate_image("$file")')
@@ -62,6 +65,8 @@ pub fn (mut ctx Context) create_image(file string) Image {
 	return img
 }
 
+// init_sokol_image initializes this `Image` for use with the
+// sokol graphical backend system.
 pub fn (mut img Image) init_sokol_image() &Image {
 	// println('\n init sokol image $img.path ok=$img.simg_ok')
 	mut img_desc := gfx.ImageDesc{
@@ -83,7 +88,7 @@ pub fn (mut img Image) init_sokol_image() &Image {
 	return img
 }
 
-// draw_image draws the provided image onto the screen
+// draw_image draws the provided image onto the screen.
 pub fn (ctx &Context) draw_image(x f32, y f32, width f32, height f32, img_ &Image) {
 	$if macos {
 		if img_.id >= ctx.image_cache.len {
@@ -150,6 +155,8 @@ pub fn (mut ctx Context) update_pixel_data(cached_image_idx int, buf &byte) {
 	image.update_pixel_data(buf)
 }
 
+// update_pixel_data updates the sokol specific pixel data associated
+// with this `Image`.
 pub fn (mut img Image) update_pixel_data(buf &byte) {
 	mut data := gfx.ImageData{}
 	data.subimage[0][0].ptr = buf
@@ -157,6 +164,9 @@ pub fn (mut img Image) update_pixel_data(buf &byte) {
 	gfx.update_image(img.simg, &data)
 }
 
+// create_image_with_size creates an `Image` from `file` in the given
+// `width` x `height` dimension.
+//
 // TODO copypasta
 pub fn (mut ctx Context) create_image_with_size(file string, width int, height int) Image {
 	if !gfx.is_valid() {
@@ -182,6 +192,8 @@ pub fn (mut ctx Context) create_image_with_size(file string, width int, height i
 	return img
 }
 
+// create_image creates an `Image` from `file`.
+//
 // TODO remove this
 fn create_image(file string) Image {
 	if !os.exists(file) {
@@ -202,6 +214,10 @@ fn create_image(file string) Image {
 	return img
 }
 
+// create_image_from_memory creates an `Image` from the
+// memory buffer `buf` of size `bufsize`.
+//
+// See also: create_image_from_byte_array
 pub fn (mut ctx Context) create_image_from_memory(buf &byte, bufsize int) Image {
 	stb_img := stbi.load_from_memory(buf, bufsize) or { return Image{} }
 	mut img := Image{
@@ -217,6 +233,10 @@ pub fn (mut ctx Context) create_image_from_memory(buf &byte, bufsize int) Image
 	return img
 }
 
+// create_image_from_byte_array creates an `Image` from the
+// byte array `b`.
+//
+// See also: create_image_from_memory
 pub fn (mut ctx Context) create_image_from_byte_array(b []byte) Image {
 	return ctx.create_image_from_memory(b.data, b.len)
 }
diff --git a/vlib/gg/image.v b/vlib/gg/image.v
index 2026bd48d1..02f63c6483 100644
--- a/vlib/gg/image.v
+++ b/vlib/gg/image.v
@@ -19,6 +19,7 @@ pub:
 	color     gx.Color = gx.white
 }
 
+// Rect represents a rectangular shape in `gg`.
 pub struct Rect {
 pub:
 	x      f32
@@ -27,6 +28,11 @@ pub:
 	height f32
 }
 
+// cache_image caches the image `img` in memory for later reuse.
+// cache_image returns the cache index of the cached image.
+//
+// See also: get_cached_image_by_idx
+// See also: remove_cached_image_by_idx
 pub fn (mut ctx Context) cache_image(img Image) int {
 	ctx.image_cache << img
 	image_idx := ctx.image_cache.len - 1
@@ -34,10 +40,19 @@ pub fn (mut ctx Context) cache_image(img Image) int {
 	return image_idx
 }
 
+// get_cached_image_by_idx returns a cached `Image` identified by `image_idx`.
+//
+// See also: cache_image
+// See also: remove_cached_image_by_idx
 pub fn (mut ctx Context) get_cached_image_by_idx(image_idx int) &Image {
 	return &ctx.image_cache[image_idx]
 }
 
+// remove_cached_image_by_idx removes an `Image` identified by `image_idx` from the
+// image cache.
+//
+// See also: cache_image
+// See also: get_cached_image_by_idx
 pub fn (mut ctx Context) remove_cached_image_by_idx(image_idx int) {
 	ctx.image_cache.delete(image_idx)
 }