Fix #1910 - Review and improve docs for 'Order' properties

src/Microsoft.AspNet.Mvc.Abstractions/IActionConstraint.cs

@@ -39,6 +39,10 @@ namespace Microsoft.AspNet.Mvc
         /// <summary>
         /// The constraint order.
         /// </summary>
+        /// <remarks>
+        /// Constraints are grouped into stages by the value of <see cref="Order"/>. See remarks on
+        /// <see cref="IActionConstraint"/>.
+        /// </remarks>
         int Order { get; }
 
         /// <summary>

src/Microsoft.AspNet.Mvc.Abstractions/IActionConstraintProvider.cs

@@ -7,8 +7,29 @@ namespace Microsoft.AspNet.Mvc.ActionConstraints
 {
     public interface IActionConstraintProvider
     {
+        /// <summary>
+        /// Gets the order value for determining the order of execution of providers. Providers execute in
+        /// ascending numeric value of the <see cref="Order"/> property.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Providers are executed in an ordering determined by an ascending sort of the <see cref="Order"/> property.
+        /// A provider with a lower numeric value of <see cref="Order"/> will have its
+        /// <see cref="OnProvidersExecuting"/> called before that of a provider with a higher numeric value of
+        /// <see cref="Order"/>. The <see cref="OnProvidersExecuted"/> method is called in the reverse ordering after
+        /// all calls to <see cref="OnProvidersExecuting"/>. A provider with a lower numeric value of
+        /// <see cref="Order"/> will have its <see cref="OnProvidersExecuted"/> method called after that of a provider
+        /// with a higher numeric value of <see cref="Order"/>.
+        /// </para>
+        /// <para>
+        /// If two providers have the same numeric value of <see cref="Order"/>, then their relative execution order
+        /// is undefined.
+        /// </para>
+        /// </remarks>
         int Order { get; }
+
         void OnProvidersExecuting([NotNull] ActionConstraintProviderContext context);
+
         void OnProvidersExecuted([NotNull] ActionConstraintProviderContext context);
     }
 }

src/Microsoft.AspNet.Mvc.Abstractions/IFilterProvider.cs

@@ -7,8 +7,29 @@ namespace Microsoft.AspNet.Mvc.Core
 {
     public interface IFilterProvider
     {
+        /// <summary>
+        /// Gets the order value for determining the order of execution of providers. Providers execute in
+        /// ascending numeric value of the <see cref="Order"/> property.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Providers are executed in an ordering determined by an ascending sort of the <see cref="Order"/> property.
+        /// A provider with a lower numeric value of <see cref="Order"/> will have its
+        /// <see cref="OnProvidersExecuting"/> called before that of a provider with a higher numeric value of
+        /// <see cref="Order"/>. The <see cref="OnProvidersExecuted"/> method is called in the reverse ordering after
+        /// all calls to <see cref="OnProvidersExecuting"/>. A provider with a lower numeric value of
+        /// <see cref="Order"/> will have its <see cref="OnProvidersExecuted"/> method called after that of a provider
+        /// with a higher numeric value of <see cref="Order"/>.
+        /// </para>
+        /// <para>
+        /// If two providers have the same numeric value of <see cref="Order"/>, then their relative execution order
+        /// is undefined.
+        /// </para>
+        /// </remarks>
         int Order { get; }
+
         void OnProvidersExecuting([NotNull] FilterProviderContext context);
+
         void OnProvidersExecuted([NotNull] FilterProviderContext context);
     }
 }

src/Microsoft.AspNet.Mvc.Abstractions/IOrderedFilter.cs

@@ -5,6 +5,34 @@ namespace Microsoft.AspNet.Mvc
 {
     public interface IOrderedFilter : IFilter
     {
+        /// <summary>
+        /// Gets the order value for determining the order of execution of filters. Filters execute in
+        /// ascending numeric value of the <see cref="Order"/> property.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Filters are executed in an ordering determined by an ascending sort of the <see cref="Order"/> property.
+        /// </para>
+        /// <para>
+        /// Asynchronous filters, such as <see cref="IAsyncActionFilter"/>, surround the execution of subsequent
+        /// filters of the same filter kind. An asynchronous filter with a lower numeric <see cref="Order"/>
+        /// value will have its filter method, such as <see cref="IAsyncActionFilter.OnActionExecutionAsync"/>,
+        /// executed before that of a filter with a higher value of <see cref="Order"/>.
+        /// </para>
+        /// <para>
+        /// Synchronous filters, such as <see cref="IActionFilter"/>, have a before-method, such as
+        /// <see cref="IActionFilter.OnActionExecuting)"/>, and an after-method, such as
+        /// <see cref="IActionFilter.OnActionExecuted"/>. A synchronous filter with a lower numeric <see cref="Order"/>
+        /// value will have its before-method executed before that of a filter with a higher value of 
+        /// <see cref="Order"/>. During the after-stage of the filter, a synchronous filter with a lower
+        /// numeric <see cref="Order"/> value will have its after-method executed after that of a filter with a higher
+        /// value of <see cref="Order"/>.
+        /// </para>
+        /// <para>
+        /// If two filters have the same numeric value of <see cref="Order"/>, then their relative execution order
+        /// is determined by the filter scope.
+        /// </para>
+        /// </remarks>
         int Order { get; }
     }
 }

src/Microsoft.AspNet.Mvc.ApiExplorer/IApiDescriptionProvider.cs

@@ -7,8 +7,29 @@ namespace Microsoft.AspNet.Mvc.ApiExplorer
 {
     public interface IApiDescriptionProvider
     {
+        /// <summary>
+        /// Gets the order value for determining the order of execution of providers. Providers execute in
+        /// ascending numeric value of the <see cref="Order"/> property.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Providers are executed in an ordering determined by an ascending sort of the <see cref="Order"/> property.
+        /// A provider with a lower numeric value of <see cref="Order"/> will have its
+        /// <see cref="OnProvidersExecuting"/> called before that of a provider with a higher numeric value of
+        /// <see cref="Order"/>. The <see cref="OnProvidersExecuted"/> method is called in the reverse ordering after
+        /// all calls to <see cref="OnProvidersExecuting"/>. A provider with a lower numeric value of
+        /// <see cref="Order"/> will have its <see cref="OnProvidersExecuted"/> method called after that of a provider
+        /// with a higher numeric value of <see cref="Order"/>.
+        /// </para>
+        /// <para>
+        /// If two providers have the same numeric value of <see cref="Order"/>, then their relative execution order
+        /// is undefined.
+        /// </para>
+        /// </remarks>
         int Order { get; }
+
         void OnProvidersExecuting([NotNull] ApiDescriptionProviderContext context);
+
         void OnProvidersExecuted([NotNull] ApiDescriptionProviderContext context);
     }
 }

src/Microsoft.AspNet.Mvc.Core/IActionDescriptorProvider.cs

@@ -7,8 +7,29 @@ namespace Microsoft.AspNet.Mvc.Core
 {
     public interface IActionDescriptorProvider
     {
+        /// <summary>
+        /// Gets the order value for determining the order of execution of providers. Providers execute in
+        /// ascending numeric value of the <see cref="Order"/> property.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Providers are executed in an ordering determined by an ascending sort of the <see cref="Order"/> property.
+        /// A provider with a lower numeric value of <see cref="Order"/> will have its
+        /// <see cref="OnProvidersExecuting"/> called before that of a provider with a higher numeric value of
+        /// <see cref="Order"/>. The <see cref="OnProvidersExecuted"/> method is called in the reverse ordering after
+        /// all calls to <see cref="OnProvidersExecuting"/>. A provider with a lower numeric value of
+        /// <see cref="Order"/> will have its <see cref="OnProvidersExecuted"/> method called after that of a provider
+        /// with a higher numeric value of <see cref="Order"/>.
+        /// </para>
+        /// <para>
+        /// If two providers have the same numeric value of <see cref="Order"/>, then their relative execution order
+        /// is undefined.
+        /// </para>
+        /// </remarks>
         int Order { get; }
+
         void OnProvidersExecuting([NotNull] ActionDescriptorProviderContext context);
+
         void OnProvidersExecuted([NotNull] ActionDescriptorProviderContext context);
     }
 }

src/Microsoft.AspNet.Mvc.Core/IActionInvokerProvider.cs

@@ -7,8 +7,29 @@ namespace Microsoft.AspNet.Mvc.Core
 {
     public interface IActionInvokerProvider
     {
+        /// <summary>
+        /// Gets the order value for determining the order of execution of providers. Providers execute in
+        /// ascending numeric value of the <see cref="Order"/> property.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Providers are executed in an ordering determined by an ascending sort of the <see cref="Order"/> property.
+        /// A provider with a lower numeric value of <see cref="Order"/> will have its
+        /// <see cref="OnProvidersExecuting"/> called before that of a provider with a higher numeric value of
+        /// <see cref="Order"/>. The <see cref="OnProvidersExecuted"/> method is called in the reverse ordering after
+        /// all calls to <see cref="OnProvidersExecuting"/>. A provider with a lower numeric value of
+        /// <see cref="Order"/> will have its <see cref="OnProvidersExecuted"/> method called after that of a provider
+        /// with a higher numeric value of <see cref="Order"/>.
+        /// </para>
+        /// <para>
+        /// If two providers have the same numeric value of <see cref="Order"/>, then their relative execution order
+        /// is undefined.
+        /// </para>
+        /// </remarks>
         int Order { get; }
+
         void OnProvidersExecuting([NotNull] ActionInvokerProviderContext context);
+
         void OnProvidersExecuted([NotNull] ActionInvokerProviderContext context);
     }
 }