Add examples for attributes (dotnet#58196)

* Add examples for a few Mvc attributes

* Scope to parameter binding attributes.

* Fixes from PR review

Author: mikekistler

src/Mvc/Mvc.Core/src/FromBodyAttribute.cs

@@ -10,9 +10,33 @@ namespace Microsoft.AspNetCore.Mvc;
 /// Specifies that a parameter or property should be bound using the request body.
 /// </summary>
 /// <remarks>
+/// Binds a parameter or property to the request body.
+///
 /// By default, ASP.NET Core MVC delegates the responsibility of reading the body to an input formatter.<br/>
 /// In the case of ASP.NET Core Minimal APIs, the body is deserialized by <see cref="System.Text.Json.JsonSerializer"/>.
+///
+/// For more information about parameter binding see
+/// <see href="https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis/parameter-binding">Parameter binding</see>.
 /// </remarks>
+/// <example>
+/// In this example, the value of the 'name' field in the form-data request body is bound to the name parameter,
+/// and the value of the 'age' field is bound to the age parameter.
+/// <code>
+/// app.MapPost("/from-body", ([FromBody] Person person) => person);
+///
+/// public record Person(string Name, int Age);
+/// </code>
+///
+/// If the EmptyBodyBehavior is set to EmptyBodyBehavior.Allow in the FromBody attribute,
+/// requests without a request body are allowed.
+/// <code>
+/// app.MapPost("/allow-empty-body",
+/// (
+///     [Description("An optional request body")]
+///     [FromBody(EmptyBodyBehavior = EmptyBodyBehavior.Allow)] Body body
+/// ) =>
+/// </code>
+/// </example>
 [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
 public class FromBodyAttribute : Attribute, IBindingSourceMetadata, IConfigureEmptyBodyBehavior, IFromBodyMetadata
 {

src/Mvc/Mvc.Core/src/FromFormAttribute.cs

@@ -9,6 +9,22 @@ namespace Microsoft.AspNetCore.Mvc;
 /// <summary>
 /// Specifies that a parameter or property should be bound using form-data in the request body.
 /// </summary>
+/// <remarks>
+/// Binds a parameter or property to a field in a form-data request body with the same name,
+/// or the name specified in the <see cref="Name"/> property.
+/// Form parameter names are matched case-insensitively.
+///
+/// For more information about parameter binding see
+/// <see href="https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis/parameter-binding">Parameter binding</see>.
+/// </remarks>
+/// <example>
+/// In this example, the value of the 'name' field in the form-data request body is bound to the name parameter,
+/// and the value of the 'age' field is bound to the age parameter.
+/// <code>
+/// app.MapPost("/from-form", ([FromForm] string name, [FromForm] int age)
+///     => new { Name = name, Age = age });
+/// </code>
+/// </example>
 [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
 public class FromFormAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromFormMetadata
 {

src/Mvc/Mvc.Core/src/FromHeaderAttribute.cs

@@ -9,6 +9,21 @@ namespace Microsoft.AspNetCore.Mvc;
 /// <summary>
 /// Specifies that a parameter or property should be bound using the request headers.
 /// </summary>
+/// <remarks>
+/// Binds a parameter or property to the value of the request header with the same name,
+/// or the name specified in the <see cref="Name"/> property.
+/// Note that HTTP header names are case-insensitive, so the header name is matched without regard to case.
+///
+/// For more information about parameter binding see
+/// <see href="https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis/parameter-binding">Parameter binding</see>.
+/// </remarks>
+/// <example>
+/// In this example, the value of the 'User-Agent' header is bound to the parameter.
+/// <code>
+/// app.MapGet("/user-agent", ([FromHeader(Name = "User-Agent")] string userAgent)
+///     => userAgent);
+/// </code>
+/// </example>
 [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
 public class FromHeaderAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromHeaderMetadata
 {

src/Mvc/Mvc.Core/src/FromQueryAttribute.cs

@@ -9,6 +9,21 @@ namespace Microsoft.AspNetCore.Mvc;
 /// <summary>
 /// Specifies that a parameter or property should be bound using the request query string.
 /// </summary>
+/// <remarks>
+/// Binds a parameter or property to the value of query string parameter with the same name,
+/// or the name specified in the <see cref="Name"/> property.
+/// The query parameter name is matched case-insensitively.
+///
+/// For more information about parameter binding see
+/// <see href="https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis/parameter-binding">Parameter binding</see>.
+/// </remarks>
+/// <example>
+/// In this example, the value of the 'User-Agent' header is bound to the parameter.
+/// <code>
+/// app.MapGet("/version", ([FromQuery(Name = "api-version")] string apiVersion)
+///     => apiVersion);
+/// </code>
+/// </example>
 [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
 public class FromQueryAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromQueryMetadata
 {

src/Mvc/Mvc.Core/src/FromRouteAttribute.cs

@@ -10,6 +10,20 @@ namespace Microsoft.AspNetCore.Mvc;
 /// <summary>
 /// Specifies that a parameter or property should be bound using route-data from the current request.
 /// </summary>
+/// <remarks>
+/// Binds a parameter or property to the value of a route parameter with the same name,
+/// or the name specified in the <see cref="Name"/> property.
+/// The route parameter name is matched against parameter segments of the route pattern case-insensitively.
+///
+/// For more information about parameter binding see
+/// <see href="https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis/parameter-binding">Parameter binding</see>.
+/// </remarks>
+/// <example>
+/// In this example, the value of the 'id' route parameter is bound to the parameter.
+/// <code>
+/// app.MapGet("/from-route/{id}", ([FromRoute] string id) => id);
+/// </code>
+/// </example>
 [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
 public class FromRouteAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromRouteMetadata
 {