Review comments

Author: TomFinley

src/Microsoft.ML.Data/Evaluators/BinaryClassifierEvaluator.cs

@@ -897,8 +897,8 @@ public sealed class CalibratedResult : Result
             /// The log-loss reduction is scaled relative to a classifier that predicts the prior for every example:
             /// (LL(prior) - LL(classifier)) / LL(prior)
             /// This metric can be interpreted as the advantage of the classifier over a random prediction.
-            /// E.g., if the RIG equals 20, it can be interpreted as "the probability of a correct prediction is
-            /// 20% better than random guessing".
+            /// E.g., if the RIG equals 20, it can be interpreted as "the probability of a correct prediction is
+            /// 20% better than random guessing."
             /// </remarks>
             public double LogLossReduction { get; }
 

src/Microsoft.ML.Data/Evaluators/RegressionEvaluator.cs

@@ -166,7 +166,7 @@ public sealed class Result
             /// </summary>
             /// <remarks>
             /// The absolute loss is defined as
-            /// L1 = (1/m) * sum( abs( yi - y'i))
+            /// L1 = (1/m) * sum( abs( yi - y&apos;i))
             /// where m is the number of instances in the test set.
             /// y'i are the predicted labels for each instance.
             /// yi are the correct labels of each instance.
@@ -178,7 +178,7 @@ public sealed class Result
             /// </summary>
             /// <remarks>
             /// The squared loss is defined as
-            /// L2 = (1/m) * sum(( yi - y'i)^2)
+            /// L2 = (1/m) * sum(( yi - y&apos;i)^2)
             /// where m is the number of instances in the test set.
             /// y'i are the predicted labels for each instance.
             /// yi are the correct labels of each instance.

src/Microsoft.ML.Data/StaticPipe/StaticPipeInternalUtils.cs

@@ -161,6 +161,23 @@ public static KeyValuePair<string, Type>[] GetNamesTypes<T, TLeaf>(ParameterInfo
             return retVal;
         }
 
+        /// <summary>
+        /// Given a schema shape defining instance, return the pairs of names and values, based on a recursive
+        /// traversal of the value-tuple. If in that list the value <c>a.b.c</c> is paired with an item <c>x</c>,
+        /// then programmatically <paramref name="record"/> when accessed as <paramref name="record"/><c>.a.b.c</c>
+        /// would be that item <c>x</c>.
+        /// </summary>
+        /// <typeparam name="T">The schema shape defining type.</typeparam>
+        /// <param name="record">The instance of that schema shape defining type, whose items will
+        /// populate the <see cref="KeyValuePair{TKey, TValue}.Value"/> fields of the returned items.</param>
+        /// <param name="pInfo">It is an implementation detail of the value-tuple type that the names
+        /// are not associated with the type at all, but there is instead an illusion propagated within
+        /// Visual Studio, that works via attributes. Programmatic access to this is limited, except that
+        /// a <see cref="TupleElementNamesAttribute"/> is attached to the type in appropriate places, e.g.,
+        /// in a delegate one of the parameters, or the return parameter, or somesuch. If present, the names
+        /// will be extracted from that structure, and if not the default names of <c>Item1</c>, <c>Item2</c>,
+        /// etc. will be used.
+        /// <returns>The set of names and corresponding values.</returns>
         public static KeyValuePair<string, PipelineColumn>[] GetNamesValues<T>(T record, ParameterInfo pInfo)
             => GetNamesValues<T, PipelineColumn>(record, pInfo);
 

src/Microsoft.ML.Data/StaticPipe/StaticPipeUtils.cs

@@ -15,8 +15,8 @@ namespace Microsoft.ML.Data.StaticPipe.Runtime
     /// <summary>
     /// Utility methods for components that want to expose themselves in the idioms of the statically-typed pipelines.
     /// These utilities are meant to be called by and useful to component authors, not users of those components. The
-    /// purpose is not to keep them hidden per se, but rather out of the face of users that are just trying to use the
-    /// library without the details of how this library is written.
+    /// purpose is not to keep them hidden per se, but rather in a place less conspicuous to users that are just trying
+    /// to use the library without writing additional components of their own.
     /// </summary>
     public static class StaticPipeUtils
     {
@@ -447,14 +447,16 @@ public string Get(PipelineColumn key, IExceptionContext ectx = null)
             internal IndexHelper(SchemaBearing<T> schematized)
             {
                 Indices = StaticPipeInternalUtils.MakeAnalysisInstance<T>(out var rec);
-                // We don't really care about this, but we need to work over something.
-                // The names will not be useful, but we will be getting those from the object's shape anyway.
+                // We define this delegate just to get its return parameter, so the name extractor has something
+                // to work over. Because this is defined without the names the names will be default, which is not
+                // useful, except we can get the "real" names from the schematized object's shape.
                 Func<T> dummyFunc = () => default;
                 var pairs = StaticPipeInternalUtils.GetNamesValues(Indices, dummyFunc.Method.ReturnParameter);
                 Contracts.Assert(pairs.Length == schematized.Shape.Pairs.Length);
 
                 var builder = ImmutableDictionary.CreateBuilder<PipelineColumn, string>();
                 for (int i = 0; i < pairs.Length; ++i)
+                    // Each "index" come from the analysis of the indices object, but we get the names from the shape.
                     builder.Add(pairs[i].Value, schematized.Shape.Pairs[i].Key);
                 Map = builder.ToImmutable();
             }