Update Maps Project API Docs (#20893)

* Update Maps Project API Docs

* Add more docs

* And more

* Apply suggestions from code review

Co-authored-by: Juan Diego Herrera <juherrera@microsoft.com>

---------

Co-authored-by: Juan Diego Herrera <juherrera@microsoft.com>

src/Controls/Maps/src/AppHostBuilderExtensions.cs

@@ -14,13 +14,17 @@
 
 namespace Microsoft.Maui.Controls.Hosting
 {
+	/// <summary>
+	/// This class contains the Map's <see cref="MauiAppBuilder"/> extensions.
+	/// </summary>
 	public static partial class AppHostBuilderExtensions
 	{
 		/// <summary>
 		/// Configures <see cref="MauiAppBuilder"/> to add support for the <see cref="Map"/> control.
 		/// </summary>
 		/// <param name="builder">The <see cref="MauiAppBuilder"/> to configure.</param>
 		/// <returns>The configured <see cref="MauiAppBuilder"/>.</returns>
+		/// <exception cref="NotImplementedException">Thrown on Windows because the maps control currently is not implemented for Windows.</exception>
 		public static MauiAppBuilder UseMauiMaps(this MauiAppBuilder builder)
 		{
 			builder
@@ -56,6 +60,12 @@ public static MauiAppBuilder UseMauiMaps(this MauiAppBuilder builder)
 			return builder;
 		}
 
+		/// <summary>
+		/// Registers the .NET MAUI Maps handlers that are needed to render the map control.
+		/// </summary>
+		/// <param name="handlersCollection">An instance of <see cref="IMauiHandlersCollection"/> on which to register the map handlers.</param>
+		/// <returns>The provided <see cref="IMauiHandlersCollection"/> object with the registered map handlers for subsequent registration calls.</returns>
+		/// <exception cref="NotImplementedException">Thrown on Windows because the maps control currently is not implemented for Windows.</exception>
 		public static IMauiHandlersCollection AddMauiMaps(this IMauiHandlersCollection handlersCollection)
 		{
 #if __ANDROID__ || __IOS__

src/Controls/Maps/src/Circle.cs

@@ -4,6 +4,9 @@
 
 namespace Microsoft.Maui.Controls.Maps
 {
+	/// <summary>
+	/// Represents a circle drawn on the map control.
+	/// </summary>
 	public partial class Circle : MapElement
 	{
 		/// <summary>Bindable property for <see cref="Center"/>.</summary>
@@ -27,18 +30,27 @@ public partial class Circle : MapElement
 			typeof(Circle),
 			null);
 
+		/// <summary>
+		/// Gets or sets the center location. This is a bindable property.
+		/// </summary>
 		public Location Center
 		{
 			get => (Location)GetValue(CenterProperty);
 			set => SetValue(CenterProperty, value);
 		}
 
+		/// <summary>
+		/// Gets or sets the radius. This is a bindable property.
+		/// </summary>
 		public Distance Radius
 		{
 			get => (Distance)GetValue(RadiusProperty);
 			set => SetValue(RadiusProperty, value);
 		}
 
+		/// <summary>
+		/// Gets or sets the fill color. This is a bindable property.
+		/// </summary>
 		public Color FillColor
 		{
 			get => (Color)GetValue(FillColorProperty);

src/Controls/Maps/src/Controls.Maps.csproj

@@ -8,7 +8,7 @@
     <Nullable>enable</Nullable>
     <_MauiDesignDllBuild Condition=" '$(OS)' != 'Unix' ">True</_MauiDesignDllBuild>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <NoWarn>$(NoWarn);CS1591;RS0041;RS0026;RS0027;RS0022</NoWarn>
+    <NoWarn>$(NoWarn);RS0041;RS0026;RS0027;RS0022</NoWarn>
     <WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
   </PropertyGroup>
 

src/Controls/Maps/src/HandlerImpl/Circle.Impl.cs

@@ -5,6 +5,7 @@ namespace Microsoft.Maui.Controls.Maps
 {
 	public partial class Circle : ICircleMapElement
 	{
+		/// <inheritdoc cref="IFilledMapElement.Fill"/>
 		public Paint? Fill => FillColor?.AsPaint();
 	}
 }

src/Controls/Maps/src/HandlerImpl/Map.Impl.cs

@@ -26,6 +26,9 @@ public partial class Map : IMap, IEnumerable<IMapPin>
 
 		}
 
+		/// <summary>
+		/// Raised when the handler for this map control changed.
+		/// </summary>
 		protected override void OnHandlerChanged()
 		{
 			base.OnHandlerChanged();

src/Controls/Maps/src/HandlerImpl/Polygon.Impl.cs

@@ -10,8 +10,14 @@ namespace Microsoft.Maui.Controls.Maps
 {
 	public partial class Polygon : IGeoPathMapElement, IFilledMapElement
 	{
+		/// <inheritdoc cref="IFilledMapElement.Fill"/>
 		public Paint? Fill => FillColor?.AsPaint();
 
+		/// <summary>
+		/// Gets or sets the location object at the specified index.
+		/// </summary>
+		/// <param name="index">The index of the location object to return or set.</param>
+		/// <returns>The location object at the specified index.</returns>
 		public Location this[int index]
 		{
 			get { return Geopath[index]; }
@@ -22,50 +28,94 @@ public Location this[int index]
 			}
 		}
 
+		/// <summary>
+		/// Gets the location object count in this polygon.
+		/// </summary>
 		public int Count => Geopath.Count;
 
+		/// <summary>
+		/// Gets whether this polygon is read-only.
+		/// </summary>
+		/// <remarks>Always returns <see langword="false"/>.</remarks>
 		public bool IsReadOnly => false;
 
+		/// <summary>
+		/// Adds a location to this polygon.
+		/// </summary>
+		/// <param name="item">The location to add.</param>
 		public void Add(Location item)
 		{
 			var index = Geopath.Count;
 			Geopath.Add(item);
 			NotifyHandler(nameof(Add), index, item);
 		}
 
+		/// <summary>
+		/// Clears all locations that make up this polygon.
+		/// </summary>
 		public void Clear()
 		{
 			for (int i = Geopath.Count - 1; i >= 0; i--)
+			{
 				RemoveAt(i);
+			}
 		}
 
+		/// <summary>
+		/// Returns whether the specified location is contained in this polygon.
+		/// </summary>
+		/// <param name="item">The location object of which to determine if it is contained in the location collection of this polygon.</param>
+		/// <returns><see langword="true"/> if <paramref name="item"/> is contained in the location collection of this polygon, otherwise <see langword="false"/>.</returns>
 		public bool Contains(Location item)
 		{
 			return Geopath.Contains(item);
 		}
 
+		/// <summary>
+		/// Copies the child locations to the specified array.
+		/// </summary>
+		/// <param name="array">The target array to copy the child views to.</param>
+		/// <param name="arrayIndex">The index at which the copying needs to start.</param>
 		public void CopyTo(Location[] array, int arrayIndex)
 		{
 			Geopath.CopyTo(array, arrayIndex);
 		}
 
+		/// <summary>
+		/// Returns an enumerator that lists all of the location object in this polygon.
+		/// </summary>
+		/// <returns>A <see cref="IEnumerator{T}"/> of type <see cref="Location"/> with all the locations in this polygon.</returns>
 		public IEnumerator<Location> GetEnumerator()
 		{
 			return Geopath.GetEnumerator();
 		}
-
+
+		/// <summary>
+		/// Gets the index of a specified location object.
+		/// </summary>
+		/// <param name="item">The location object of which to determine the index.</param>
+		/// <returns>The index of the specified location, if the location was not found this will return <c>-1</c>.</returns>
 		public int IndexOf(Location item)
 		{
 			return Geopath.IndexOf(item);
 		}
 
+		/// <summary>
+		/// Inserts a location object at the specified index.
+		/// </summary>
+		/// <param name="index">The index at which to specify the location object.</param>
+		/// <param name="item">The location object to insert.</param>
 		public void Insert(int index, Location item)
 		{
 			Geopath.Insert(index, item);
 			NotifyHandler(nameof(Insert), index, item);
-
 		}
 
+		/// <summary>
+		/// Removes a location object from this polygon.
+		/// </summary>
+		/// <param name="item">The location object to remove.</param>
+		/// <returns><see langword="true"/> if the location was removed successfully, otherwise <see langword="false"/>.</returns>
 		public bool Remove(Location item)
 		{
 			var index = Geopath.IndexOf(item);
@@ -74,6 +124,10 @@ public bool Remove(Location item)
 			return result;
 		}
 
+		/// <summary>
+		/// Removes a location object at the specified index.
+		/// </summary>
+		/// <param name="index">The index at which to remove the location.</param>
 		public void RemoveAt(int index)
 		{
 			var item = Geopath[index];

src/Controls/Maps/src/HandlerImpl/Polyline.Impl.cs

@@ -11,6 +11,11 @@ namespace Microsoft.Maui.Controls.Maps
 {
 	public partial class Polyline : IGeoPathMapElement
 	{
+		/// <summary>
+		/// Gets or sets the location object at the specified index.
+		/// </summary>
+		/// <param name="index">The index of the location object to return or set.</param>
+		/// <returns>The location object at the specified index.</returns>
 		public Location this[int index]
 		{
 			get { return Geopath[index]; }
@@ -21,50 +26,95 @@ public Location this[int index]
 			}
 		}
 
+		/// <summary>
+		/// Gets the location object count in this polyline.
+		/// </summary>
 		public int Count => Geopath.Count;
 
+		/// <summary>
+		/// Gets whether this polyline is read-only.
+		/// </summary>
+		/// <remarks>Always returns <see langword="false"/>.</remarks>
 		public bool IsReadOnly => false;
 
+		/// <summary>
+		/// Adds a location to this polyline.
+		/// </summary>
+		/// <param name="item">The location to add.</param>
 		public void Add(Location item)
 		{
 			var index = Geopath.Count;
 			Geopath.Add(item);
 			NotifyHandler(nameof(Add), index, item);
 		}
 
+		/// <summary>
+		/// Clears all locations that make up this polyline.
+		/// </summary>
 		public void Clear()
 		{
 			for (int i = Geopath.Count - 1; i >= 0; i--)
+			{
 				RemoveAt(i);
+			}
 		}
 
+		/// <summary>
+		/// Returns whether the specified location is contained in this polyline.
+		/// </summary>
+		/// <param name="item">The location object of which to determine if it is contained in the location collection of this polyline.</param>
+		/// <returns><see langword="true"/> if <paramref name="item"/> is contained in the location collection of this polyline, otherwise <see langword="false"/>.</returns>
 		public bool Contains(Location item)
 		{
 			return Geopath.Contains(item);
 		}
 
+		/// <summary>
+		/// Copies the child locations to the specified array.
+		/// </summary>
+		/// <param name="array">The target array to copy the child views to.</param>
+		/// <param name="arrayIndex">The index at which the copying needs to start.</param>
 		public void CopyTo(Location[] array, int arrayIndex)
 		{
 			Geopath.CopyTo(array, arrayIndex);
 		}
 
+		/// <summary>
+		/// Returns an enumerator that lists all of the location object in this polyline.
+		/// </summary>
+		/// <returns>A <see cref="IEnumerator{T}"/> of type <see cref="Location"/> with all the locations in this polyline.</returns>
 		public IEnumerator<Location> GetEnumerator()
 		{
 			return Geopath.GetEnumerator();
 		}
 
+		/// <summary>
+		/// Gets the index of a specified location object.
+		/// </summary>
+		/// <param name="item">The location object of which to determine the index.</param>
+		/// <returns>The index of the specified location, if the location was not found this will return <c>-1</c>.</returns>
 		public int IndexOf(Location item)
 		{
 			return Geopath.IndexOf(item);
 		}
 
+		/// <summary>
+		/// Inserts a location object at the specified index.
+		/// </summary>
+		/// <param name="index">The index at which to specify the location object.</param>
+		/// <param name="item">The location object to insert.</param>
 		public void Insert(int index, Location item)
 		{
 			Geopath.Insert(index, item);
 			NotifyHandler(nameof(Insert), index, item);
 
 		}
 
+		/// <summary>
+		/// Removes a location object from this polyline.
+		/// </summary>
+		/// <param name="item">The location object to remove.</param>
+		/// <returns><see langword="true"/> if the location was removed successfully, otherwise <see langword="false"/>.</returns>
 		public bool Remove(Location item)
 		{
 			var index = Geopath.IndexOf(item);
@@ -73,6 +123,10 @@ public bool Remove(Location item)
 			return result;
 		}
 
+		/// <summary>
+		/// Removes a location object at the specified index.
+		/// </summary>
+		/// <param name="index">The index at which to remove the location.</param>
 		public void RemoveAt(int index)
 		{
 			var item = Geopath[index];