Refine descriptions of Microsoft.ML classes (#3446)

Author: natke

src/Microsoft.ML.Core/Data/ModelSaveContext.cs

@@ -11,11 +11,13 @@
 namespace Microsoft.ML
 {
  /// <summary>
- /// This is a convenience context object for saving models to a repository, for
- /// implementors of <see cref="ICanSaveModel"/>. It is not mandated but designed to reduce the
- /// amount of boiler plate code. It can also be used when saving to a single stream,
- /// for implementors of <see cref="ICanSaveInBinaryFormat"/>.
+ /// Convenience context object for saving models to a repository, for
+ /// implementors of <see cref="ICanSaveModel"/>.
  /// </summary>
+ /// <remarks>
+ /// This class reduces the amount of boiler plate code needed to implement <see cref="ICanSaveModel"/>.
+ /// It can also be used when saving to a single stream, for implementors of <see cref="ICanSaveInBinaryFormat"/>.
+ /// </remarks>
  public sealed partial class ModelSaveContext : IDisposable
  {
  /// <summary>

src/Microsoft.ML.Core/Prediction/TrainerInfo.cs

@@ -5,7 +5,7 @@
 namespace Microsoft.ML
 {
  /// <summary>
- /// Instances of this class posses information about trainers, in terms of their requirements and capabilities.
+ /// Characteristics of a trainer. Exposed via the Info property of each trainer.
  /// </summary>
  public sealed class TrainerInfo
  {

src/Microsoft.ML.Data/DataLoadSave/Binary/BinaryLoaderSaverCatalog.cs

@@ -9,6 +9,10 @@
 
 namespace Microsoft.ML
 {
+ /// <summary>
+ /// Collection of extension methods for the <see cref="DataOperationsCatalog"/> to create instances of
+ /// components to save and read <see cref="IDataView"/> objects to and from a high-performance binary format.
+ /// </summary>
  public static class BinaryLoaderSaverCatalog
  {
  /// <summary>

src/Microsoft.ML.Data/DataLoadSave/DataLoaderExtensions.cs

@@ -6,6 +6,9 @@
 
 namespace Microsoft.ML
 {
+ /// <summary>
+ /// Class used to load data from one or more files.
+ /// </summary>
  public static class DataLoaderExtensions
  {
  /// <summary>

src/Microsoft.ML.Data/DataLoadSave/DataOperationsCatalog.cs

@@ -11,8 +11,8 @@
 namespace Microsoft.ML
 {
  /// <summary>
- /// A catalog of operations over data that are not transformers or estimators.
- /// This includes data loaders, saving, caching, filtering etc.
+ /// Class used to create components that operate on data, but are not part of the model training pipeline.
+ /// Includes components to load, save, cache, filter, shuffle, and split data.
  /// </summary>
  public sealed class DataOperationsCatalog : IInternalCatalog
  {

src/Microsoft.ML.Data/DataLoadSave/EstimatorExtensions.cs

@@ -10,7 +10,7 @@
 namespace Microsoft.ML
 {
  /// <summary>
- /// Extension methods that allow chaining estimator and transformer pipes together.
+ /// Extension methods that allow chaining of estimator and transformer pipelines.
  /// </summary>
  public static class LearningPipelineExtensions
  {

src/Microsoft.ML.Data/DataLoadSave/Text/TextLoaderSaverCatalog.cs

@@ -9,6 +9,10 @@
 
 namespace Microsoft.ML
 {
+ /// <summary>
+ /// Collection of extension methods for the <see cref="DataOperationsCatalog"/> to read from delimited text
+ /// files such as csv and tsv.
+ /// </summary>
  public static class TextLoaderSaverCatalog
  {
  /// <summary>

src/Microsoft.ML.Data/DebuggerExtensions.cs

@@ -9,7 +9,8 @@
 namespace Microsoft.ML
 {
  /// <summary>
- /// Static extensions for data preview.
+ /// Class used to create instances of preview objects for debugging.
+ /// Note: this class and all methods should only be used for debugging and not in production code.
  /// </summary>
  public static class DebuggerExtensions
  {

src/Microsoft.ML.Data/MLContext.cs

@@ -10,8 +10,9 @@
 namespace Microsoft.ML
 {
  /// <summary>
- /// The <see cref="MLContext"/> is a starting point for all ML.NET operations. It is instantiated by user,
- /// provides mechanisms for logging and entry points for training, prediction, model operations etc.
+ /// The common context for all ML.NET operations. Once instantiated by the user, it provides a way to
+ /// create components for data preparation, feature enginering, training, prediction, model evaluation.
+ /// It also allows logging, execution control, and the ability set repeatable random numbers.
  /// </summary>
  public sealed class MLContext : IHostEnvironment
  {

src/Microsoft.ML.Data/Model/ModelOperationsCatalog.cs

@@ -13,7 +13,7 @@
 namespace Microsoft.ML
 {
  /// <summary>
- /// An object serving as a 'catalog' of available model operations.
+ /// Class used by <see cref="MLContext"/> to save and load trained models.
  /// </summary>
  public sealed class ModelOperationsCatalog : IInternalCatalog
  {