Document ICanvas (#20881)

* Document ICanvas

* Fix typo

* Added missing params

* Add missing return

src/Graphics/src/Graphics/ICanvas.cs

@@ -3,54 +3,236 @@
 
 namespace Microsoft.Maui.Graphics
 {
+	/// <summary>
+	/// Represents a platform-agnostic canvas on which 2D graphics can be drawn using types from the <see cref="Microsoft.Maui.Graphics"/> namespace.
+	/// </summary>
 	public interface ICanvas
 	{
+		/// <summary>
+		/// Gets or sets a value that represents the scaling factor to scale the UI by. 
+		/// </summary>
 		public float DisplayScale { get; set; }
+
+		/// <summary>
+		/// Sets the width of the stroke used to draw an object's outline.
+		/// </summary>
 		public float StrokeSize { set; }
+
+		/// <summary>
+		/// Sets the limit of the miter length of line joins in an object.
+		/// </summary>
 		public float MiterLimit { set; }
+
+		/// <summary>
+		/// Sets the <see cref="Color"/> used to paint an object's outline.
+		/// </summary>
 		public Color StrokeColor { set; }
+
+		/// <summary>
+		/// Sets the shape at the start and end of a line.
+		/// </summary>
 		public LineCap StrokeLineCap { set; }
+
+		/// <summary>
+		/// Sets the type of join used at the vertices of a shape.
+		/// </summary>
 		public LineJoin StrokeLineJoin { set; }
+
+		/// <summary>
+		/// Sets the pattern of dashes and gaps that are used to outline an object.
+		/// </summary>
 		public float[] StrokeDashPattern { set; }
+
+		/// <summary>
+		/// Sets the distance within the dash pattern where a dash begins.
+		/// </summary>
 		public float StrokeDashOffset { set; }
+
+		/// <summary>
+		/// Sets the color used to paint an object's interior.
+		/// </summary>
 		public Color FillColor { set; }
+
+		/// <summary>
+		/// Sets the font color when drawing text.
+		/// </summary>
 		public Color FontColor { set; }
+
+		/// <summary>
+		/// Sets the font used when drawing text.
+		/// </summary>
 		public IFont Font { set; }
+
+		/// <summary>
+		/// Sets the size of the font used when drawing text.
+		/// </summary>
 		public float FontSize { set; }
+
+		/// <summary>
+		/// Sets the opacity of am object.
+		/// </summary>
 		public float Alpha { set; }
+
+		/// <summary>
+		/// Sets a value that indicates whether to use anti-aliasing is enabled.
+		/// </summary>
 		public bool Antialias { set; }
+
+		/// <summary>
+		/// Sets the blend mode, which determines what happens when an object is rendered on top of an existing object.
+		/// </summary>
 		public BlendMode BlendMode { set; }
 
+		/// <summary>
+		/// Draws the specified <paramref name="path"/> onto the canvas.
+		/// </summary>
+		/// <param name="path">The path to be drawn.</param>
 		public void DrawPath(PathF path);
 
+		/// <summary>
+		/// Draws and fills the specified <paramref name="path"/> onto the canvas.
+		/// </summary>
+		/// <param name="path">The path to be drawn.</param>
+		/// <param name="windingMode">The fill algorithm to be used.</param>
 		public void FillPath(PathF path, WindingMode windingMode);
 
+		/// <summary>
+		/// Clips an object so that only the area outside the of a rectangle will be visible.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate of the rectangle.</param>
+		/// <param name="y">Starting <c>y</c> coordinate of the rectangle.</param>
+		/// <param name="width">Width of the rectangle.</param>
+		/// <param name="height">Height of the rectangle.</param>
 		public void SubtractFromClip(float x, float y, float width, float height);
 
+		/// <summary>
+		/// Clips an object so that only the area outside of a <see cref="PathF"/> object will be visible.
+		/// </summary>
+		/// <param name="path">The path used to clip the object</param>
+		/// <param name="windingMode">Fill algorithm used for the path. Default is <see cref="WindingMode.NonZero"/>.</param>
 		public void ClipPath(PathF path, WindingMode windingMode = WindingMode.NonZero);
 
+		/// <summary>
+		/// Clips an object so that only the area that's within the region of the rectangle will be visible.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate of the rectangle.</param>
+		/// <param name="y">Starting <c>y</c> coordinate of the rectangle.</param>
+		/// <param name="width">Width of the rectangle.</param>
+		/// <param name="height">Height of the rectangle.</param>
 		public void ClipRectangle(float x, float y, float width, float height);
 
+		/// <summary>
+		/// Draws a line between two points onto the canvas.
+		/// </summary>
+		/// <param name="x1">Starting <c>x</c> coordinate.</param>
+		/// <param name="y1">Starting <c>y</c> coordinate.</param>
+		/// <param name="x2">Ending <c>x</c> coordinate.</param>
+		/// <param name="y2">Ending <c>x</c> coordinate.</param>
 		public void DrawLine(float x1, float y1, float x2, float y2);
 
+		/// <summary>
+		/// Draws an arc onto the canvas.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the arc.</param>
+		/// <param name="height">Height of the arc.</param>
+		/// <param name="startAngle">The angle from the x-axis to the start point of the arc.</param>
+		/// <param name="endAngle">The angle from the x-axis to the end point of the arc.</param>
+		/// <param name="clockwise"><see langword="true"/> to draw the arc in a clockwise direction; <see langword="false"/> to draw the arc counterclockwise.</param>
+		/// <param name="closed"><see langword="true"/> to specify whether the end point of the arc will be connected to the start point; <see langword="false"/> otherwise.</param>
 		public void DrawArc(float x, float y, float width, float height, float startAngle, float endAngle, bool clockwise, bool closed);
 
+		/// <summary>
+		/// Draws a filled arc onto the canvas.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the arc.</param>
+		/// <param name="height">Height of the arc.</param>
+		/// <param name="startAngle">The angle from the x-axis to the start point of the arc.</param>
+		/// <param name="endAngle">The angle from the x-axis to the end point of the arc.</param>
+		/// <param name="clockwise"><see langword="true"/> to draw the arc in a clockwise direction; <see langword="false"/> to draw the arc counterclockwise.</param>
 		public void FillArc(float x, float y, float width, float height, float startAngle, float endAngle, bool clockwise);
 
+		/// <summary>
+		/// Draws a rectangle onto the canvas.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the rectangle.</param>
+		/// <param name="height">Height of the rectangle.</param>
 		public void DrawRectangle(float x, float y, float width, float height);
 
+		/// <summary>
+		/// Draws a filled rectangle onto the canvas.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the rectangle.</param>
+		/// <param name="height">Height of the rectangle.</param>
 		public void FillRectangle(float x, float y, float width, float height);
 
+		/// <summary>
+		/// Draws a rectangle with rounded corners onto the canvas.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the rectangle.</param>
+		/// <param name="height">Height of the rectangle.</param>
+		/// <param name="cornerRadius">The radius used to round the corners of the rectangle.</param>
 		public void DrawRoundedRectangle(float x, float y, float width, float height, float cornerRadius);
 
+		/// <summary>
+		/// Draws a filled rectangle with rounded corners onto the canvas.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the rectangle.</param>
+		/// <param name="height">Height of the rectangle.</param>
+		/// <param name="cornerRadius">The radius used to round the corners of the rectangle.</param>
 		public void FillRoundedRectangle(float x, float y, float width, float height, float cornerRadius);
 
+		/// <summary>
+		/// Draws an ellipse onto the canvas.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the ellipse.</param>
+		/// <param name="height">Height of the ellipse.</param>
 		public void DrawEllipse(float x, float y, float width, float height);
 
+		/// <summary>
+		/// Draws a filled ellipse onto the canvas.
+		/// </summary>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the ellipse.</param>
+		/// <param name="height">Height of the ellipse.</param>
 		public void FillEllipse(float x, float y, float width, float height);
 
+		/// <summary>
+		/// Draws a text string onto the canvas.
+		/// </summary>
+		/// <remarks>To draw attributed text, use <see cref="DrawText(IAttributedText, float, float, float, float)"/> instead.</remarks>
+		/// <param name="value">Text to be displayed.</param>
+		/// <param name="x">Starting <c>x</c> coordinate.</param>
+		/// <param name="y">Starting <c>y</c> coordinate.</param>
+		/// <param name="horizontalAlignment">Horizontal alignment options to align the string.</param>
 		public void DrawString(string value, float x, float y, HorizontalAlignment horizontalAlignment);
 
+		/// <summary>
+		/// Draws a text string within a bounding box onto the canvas.
+		/// </summary>
+		/// <param name="value">Text to be displayed.</param>
+		/// <param name="x">Starting <c>x</c> coordinate of the bounding box.</param>
+		/// <param name="y">Starting <c>y</c> coordinate of the bounding box.</param>
+		/// <param name="width">Width of the bounding box.</param>
+		/// <param name="height">Height of the bounding box.</param>
+		/// <param name="horizontalAlignment">Horizontal alignment options to align the string within the bounding box.</param>
+		/// <param name="verticalAlignment">Vertical alignment options to align the string within the bounding box.</param>
+		/// <param name="textFlow">Specifies whether text will be clipped in case it overflows the bounding box. Default is <see cref="TextFlow.ClipBounds"/>.</param>
+		/// <param name="lineSpacingAdjustment">Spacing adjustment between lines. Default is 0.</param>
 		public void DrawString(
 			string value,
 			float x,
@@ -62,37 +244,117 @@ public void DrawString(
 			TextFlow textFlow = TextFlow.ClipBounds,
 			float lineSpacingAdjustment = 0);
 
+		/// <summary>
+		/// Draws attributed text within a bounding box onto the canvas.
+		/// </summary>
+		/// <param name="value">Attributed text to be displayed.</param>
+		/// <param name="x">Starting <c>x</c> coordinate of the bounding box.</param>
+		/// <param name="y">Starting <c>y</c> coordinate of the bounding box.</param>
+		/// <param name="width">Width of the bounding box.</param>
+		/// <param name="height">Height of the bounding box.</param>
 		public void DrawText(
 			IAttributedText value,
 			float x,
 			float y,
 			float width,
 			float height);
 
+		/// <summary>
+		/// Rotates a graphical object around a point.
+		/// </summary>
+		/// <remarks>Rotation is clockwise for increasing angles. Negative angles and angles greater than 360 are allowed.</remarks>
+		/// <param name="degrees">Rotation angle.</param>
+		/// <param name="x"><c>x</c> coordinate of the rotation point.</param>
+		/// <param name="y"><c>y</c> coordinate of the rotation point.</param>
 		public void Rotate(float degrees, float x, float y);
 
+		/// <summary>
+		/// Rotates a graphical object around the upper-left corner of the canvas (0,0).
+		/// </summary>
+		/// <remarks>Rotation is clockwise for increasing angles. Negative angles and angles greater than 360 are allowed.</remarks>
 		public void Rotate(float degrees);
 
+
+		/// <summary>
+		/// Changes the size of a graphical object by scaling it.
+		/// </summary>
+		/// <remarks>Can cause starting coordinates to move when an object is made larger.</remarks>
+		/// <param name="sx">Value for horizontal scaling.</param>
+		/// <param name="sy">Value for vertical scaling.</param>
 		public void Scale(float sx, float sy);
 
+		/// <summary>
+		/// Shifts a graphical object in horizontal and vertical directions.
+		/// </summary>
+		/// <param name="tx">Horizontal shift. Negative values move the object to the left, while positive values move it to the right.</param>
+		/// <param name="ty">Vertical shift. Negative values move the object down, while positive values move it up.</param>
 		public void Translate(float tx, float ty);
 
+		/// <summary>
+		/// Applies transformation specified by <paramref name="transform"/> to a graphical object.
+		/// </summary>
+		/// <param name="transform">Affine transformation matrix.</param>
 		public void ConcatenateTransform(Matrix3x2 transform);
 
+		/// <summary>
+		/// Saves the current graphics state.
+		/// </summary>
 		public void SaveState();
 
+		/// <summary>
+		/// Restores the graphics state to the most recently saved state.
+		/// </summary>
+		/// <returns><see langword="true"/> if the restore was succesful, <see langword="false"/> otherwise.</returns>
 		public bool RestoreState();
 
+		/// <summary>
+		/// Resets the graphics state to its default values.
+		/// </summary>
 		public void ResetState();
 
+		/// <summary>
+		/// Adds a shadow to a graphical object.
+		/// </summary>
+		/// <param name="offset">Represents the position of a light source that creates the shadow.</param>
+		/// <param name="blur">Amount of blur to apply to the shadow.</param>
+		/// <param name="color">Color of the shadow.</param>
 		public void SetShadow(SizeF offset, float blur, Color color);
 
+		/// <summary>
+		/// Sets <paramref name="paint"/> as the fill of a graphical object.
+		/// </summary>
+		/// <param name="paint">Paint to set as fill</param>
+		/// <param name="rectangle">Rectangle to apply a gradient on if the <paramref name="paint"/> supports it.</param>
 		public void SetFillPaint(Paint paint, RectF rectangle);
 
+		/// <summary>
+		/// Draws an image onto the canvas.
+		/// </summary>
+		/// <param name="image">Image to display</param>
+		/// <param name="x">Top left corner <c>x</c> coordinate.</param>
+		/// <param name="y">Top left corner <c>y</c> coordinate.</param>
+		/// <param name="width">Width of the image.</param>
+		/// <param name="height">Height of the image.</param>
 		public void DrawImage(IImage image, float x, float y, float width, float height);
 
+		/// <summary>
+		/// Calculates the area a string would occupy if drawn on the canvas.
+		/// </summary>
+		/// <param name="value">String to calculate the size on.</param>
+		/// <param name="font">The string's font type.</param>
+		/// <param name="fontSize">The string's font size.</param>
+		/// <returns>The area the string would occupy on the canvas.</returns>
 		public SizeF GetStringSize(string value, IFont font, float fontSize);
 
+		/// <summary>
+		/// Calculates the area a string would occupy if drawn on the canvas.
+		/// </summary>
+		/// <param name="value">String to calculate the size on.</param>
+		/// <param name="font">The string's font type.</param>
+		/// <param name="fontSize">The string's font size.</param>
+		/// <param name="horizontalAlignment">Horizontal alignment options for the string.</param>
+		/// <param name="verticalAlignment">Vertical alignment options for the string.</param>
+		/// <returns>The area the string would occupy on the canvas.</returns>
 		public SizeF GetStringSize(string value, IFont font, float fontSize, HorizontalAlignment horizontalAlignment, VerticalAlignment verticalAlignment);
 	}
 }