Improve documentation of some gui, forms, and canvas Lua functions

see #3851

src/BizHawk.Client.Common/lua/CommonLibs/GuiLuaLibrary.cs

@@ -121,8 +121,14 @@ public void DrawEllipse(
 			string surfaceName = null)
 				=> APIs.Gui.DrawEllipse(x, y, width, height, _th.SafeParseColor(line), _th.SafeParseColor(background), surfaceID: UseOrFallback(surfaceName));
 
-		[LuaMethodExample("gui.drawIcon( \"C:\\sample.ico\", 16, 32, 18, 24 );")]
-		[LuaMethod("drawIcon", "draws an Icon (.ico) file from the given path at the given coordinate. width and height are optional. If specified, it will resize the image accordingly")]
+		[LuaMethodExample("""
+			gui.drawIcon("C:\\sample.ico", 16, 32, 18, 24);
+		""")]
+		[LuaMethod(
+			name: "drawIcon",
+			description: "Draws the image in the given .ico file to the surface specified by the surfaceName parameter, or the current surface if nil/unset."
+				+ " The image will be positioned such that its top-left corner will be at (x, y) on the surface."
+				+ " If width and height are both nil/unset, the image will be drawn at full size (100%). If both are specified, the image will be stretched to that size.")]
 		public void DrawIcon(
 			string path,
 			int x,
@@ -132,8 +138,15 @@ public void DrawIcon(
 			string surfaceName = null)
 				=> APIs.Gui.DrawIcon(path, x, y, width, height, surfaceID: UseOrFallback(surfaceName));
 
-		[LuaMethodExample("gui.drawImage( \"C:\\sample.bmp\", 16, 32, 18, 24, false );")]
-		[LuaMethod("drawImage", "draws an image file from the given path at the given coordinate. width and height are optional. If specified, it will resize the image accordingly")]
+		[LuaMethodExample("""
+			gui.drawImage("C:\\sample.bmp", 16, 32, 18, 24, false);
+		""")]
+		[LuaMethod(
+			name: "drawImage",
+			description: "Draws the image in the given file (.bmp, .gif, .jpg, .png, or .tif) to the surface specified by the surfaceName parameter, or the current surface if nil/unset."
+				+ " The image will be positioned such that its top-left corner will be at (x, y) on the surface."
+				+ " If width and height are both nil/unset, the image will be drawn at full size (100%). If both are specified, the image will be stretched to that size." // technically width or height can be specified w/o the other but let's leave that as UB
+				+ " If true is passed for the cache parameter, or if it's omitted, the file contents will be cached and re-used next time this function is called with the same path. The cache can be cleared with gui.clearImageCache.")]
 		public void DrawImage(
 			string path,
 			int x,
@@ -149,8 +162,14 @@ public void DrawImage(
 		public void ClearImageCache()
 			=> APIs.Gui.ClearImageCache();
 
-		[LuaMethodExample("gui.drawImageRegion( \"C:\\sample.png\", 11, 22, 33, 44, 21, 43, 34, 45 );")]
-		[LuaMethod("drawImageRegion", "draws a given region of an image file from the given path at the given coordinate, and optionally with the given size")]
+		[LuaMethodExample("""
+			gui.drawImageRegion("C:\\sample.png", 11, 22, 33, 44, 21, 43, 34, 45);
+		""")]
+		[LuaMethod(
+			name: "drawImageRegion",
+			description: "Draws part of the image in the given file (.bmp, .gif, .jpg, .png, or .tif) to the surface specified by the surfaceName parameter, or the current surface if nil/unset."
+				+ " Consult this diagram to see its usage (renders embedded on the TASVideos Wiki): [https://user-images.githubusercontent.com/13409956/198868522-55dc1e5f-ae67-4ebb-a75f-558656cb4468.png|alt=Diagram showing how to use forms.drawImageRegion]"
+				+ " The file contents will be cached and re-used next time this function is called with the same path. The cache can be cleared with gui.clearImageCache.")]
 		public void DrawImageRegion(
 			string path,
 			int source_x,
@@ -208,8 +227,16 @@ public void DrawPixel(
 			string surfaceName = null)
 				=> APIs.Gui.DrawPixel(x, y, _th.SafeParseColor(color), surfaceID: UseOrFallback(surfaceName));
 
-		[LuaMethodExample("gui.drawPolygon( { { 5, 10 }, { 10, 10 }, { 10, 20 }, { 5, 20 } }, 10, 30, 0x007F00FF, 0x7F7F7FFF );")]
-		[LuaMethod("drawPolygon", "Draws a polygon using the table of coordinates specified in points. This should be a table of tables(each of size 2). If x or y is passed, the polygon will be translated by the passed coordinate pair. Line is the color of the polygon. Background is the optional fill color")]
+		[LuaMethodExample("""
+			gui.drawPolygon({ { 5, 10 }, { 10, 10 }, { 10, 20 }, { 5, 20 } }, 10, 30, 0x007F00FF, 0x7F7F7FFF);
+		""")]
+		[LuaMethod(
+			name: "drawPolygon",
+			description: "Draws a polygon (cyclic polyline) to the surface specified by the surfaceName parameter, or the current surface if nil/unset."
+				+ " The polygon must be given as a list of length-2 lists (co-ordinate pairs). Each pair is interpreted as the absolute co-ordinates of one of the vertices, and these are joined together in sequence to form a polygon. The last is connected to the first; you DON'T need to end with a copy of the first to close the cycle."
+				+ " If the offsetX and offsetY parameters are both specified, the whole polygon will be offset by that amount." // technically x or y can be specified w/o the other but let's leave that as UB
+				+ " If a value is passed for the line parameter, the polygon's edges are drawn in that color (i.e. the stroke color)."
+				+ " If a value is passed for the background parameter, the polygon's face is filled in that color.")]
 		public void DrawPolygon(
 			LuaTable points,
 			int? offsetX = null,
@@ -326,8 +353,14 @@ public void Text(
 			string anchor = null)
 				=> APIs.Gui.Text(x, y, message, _th.SafeParseColor(forecolor), anchor);
 
-		[LuaMethodExample("local nlguicre = gui.createcanvas( 77, 99, 2, 48 );")]
-		[LuaMethod("createcanvas", "Creates a canvas of the given size and, if specified, the given coordinates.")]
+		[LuaMethodExample("""
+			local canvas = gui.createcanvas(77, 99, 2, 48);
+		""")]
+		[LuaMethod(
+			name: "createcanvas",
+			description: "Creates a dedicated canvas window, returning a table containing some callbacks for drawing. These are the LuaCanvas functions in the API reference."
+				+ " The width and height parameters determine the size of the canvas."
+				+ " If the x and y parameters are both nil/unset, the form (window) will appear at the default position. If both are specified, the form will be positioned at (x, y) on the screen.")] // technically x can be specified w/o y but let's leave that as UB
 		public LuaTable CreateCanvas(int width, int height, int? x = null, int? y = null)
 			=> CreateLuaCanvasCallback(width, height, x, y);