From 30741e91b4e98168a8adf7be0b525f41b6d43b03 Mon Sep 17 00:00:00 2001
From: Zeeshan Siddiqui <mzs@microsoft.com>
Date: Thu, 18 Apr 2019 12:14:46 -0700
Subject: [PATCH 1/2] XML documentation for Poisson Regression trainer.

---
 .../PoissonRegression/PoissonRegression.cs    | 24 ++++++++++++++++---
 .../StandardTrainersCatalog.cs                |  8 +++----
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/Microsoft.ML.StandardTrainers/Standard/PoissonRegression/PoissonRegression.cs b/src/Microsoft.ML.StandardTrainers/Standard/PoissonRegression/PoissonRegression.cs
index b7d5ce4edd..e64ace20af 100644
--- a/src/Microsoft.ML.StandardTrainers/Standard/PoissonRegression/PoissonRegression.cs
+++ b/src/Microsoft.ML.StandardTrainers/Standard/PoissonRegression/PoissonRegression.cs
@@ -28,12 +28,30 @@ namespace Microsoft.ML.Trainers
     /// The <see cref="IEstimator{TTransformer}"/> for training a Poisson regression model.
     /// </summary>
     /// <remarks>
-    /// <a href='https://en.wikipedia.org/wiki/Poisson_regression'>Poisson regression</a> is a parameterized regression method.
+    /// <format type="text/markdown"><![CDATA[
+    /// To create this trainer, use [LbfgsPoissonRegression](xref:Microsoft.ML.StandardTrainersCatalog.LbfgsPoissonRegression(Microsoft.ML.RegressionCatalog.RegressionTrainers,System.String,System.String,System.String,System.Single,System.Single,System.Single,System.Int32,System.Boolean))
+    /// or [LbfgsPoissonRegression(Options)](xref:Microsoft.ML.StandardTrainersCatalog.LbfgsPoissonRegression(Microsoft.ML.RegressionCatalog.RegressionTrainers,Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer.Options)).
+    ///
+    /// [!include[io](~/../docs/samples/docs/api-reference/io-columns-regression.md)]
+    ///
+    /// ### Trainer Characteristics
+    /// |  |  |
+    /// | -- | -- |
+    /// | Machine learning task | Regression |
+    /// | Is normalization required? | Yes |
+    /// | Is caching required? | No |
+    /// | Required NuGet in addition to Microsoft.ML | None |
+    ///
+    /// ### Training Algorithm Details
+    /// [Poisson regression](https://en.wikipedia.org/wiki/Poisson_regression) is a parameterized regression method.
     /// It assumes that the log of the conditional mean of the dependent variable follows a linear function of the dependent variables.
     /// Assuming that the dependent variable follows a Poisson distribution, the regression parameters can be estimated by maximizing the likelihood of the obtained observations.
+    /// ]]>
+    /// </format>
     /// </remarks>
-    /// <seealso cref="StandardTrainersCatalog.LbfgsPoissonRegression(RegressionCatalog.RegressionTrainers, string, string, string, float, float, float, int, bool)"/>
-    /// <seealso cref="StandardTrainersCatalog.LbfgsPoissonRegression(RegressionCatalog.RegressionTrainers, Options)"/>
+    /// <seealso cref="Microsoft.ML.StandardTrainersCatalog.LbfgsPoissonRegression(Microsoft.ML.RegressionCatalog.RegressionTrainers,System.String,System.String,System.String,System.Single,System.Single,System.Single,System.Int32,System.Boolean)"/>
+    /// <seealso cref="Microsoft.ML.StandardTrainersCatalog.LbfgsPoissonRegression(Microsoft.ML.RegressionCatalog.RegressionTrainers,Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer.Options)"/>
+    /// <seealso cref="Options"/>
     public sealed class LbfgsPoissonRegressionTrainer : LbfgsTrainerBase<LbfgsPoissonRegressionTrainer.Options, RegressionPredictionTransformer<PoissonRegressionModelParameters>, PoissonRegressionModelParameters>
     {
         internal const string LoadNameValue = "PoissonRegression";
diff --git a/src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs b/src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs
index 3a0a808cc1..601950b948 100644
--- a/src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs
+++ b/src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs
@@ -573,11 +573,11 @@ public static LbfgsLogisticRegressionBinaryTrainer LbfgsLogisticRegression(this
         }
 
         /// <summary>
-        /// Predict a target using a linear regression model trained with the <see cref="Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer"/> trainer.
+        /// Creates a <see cref="Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer"/>, which predicts a target using a linear regression model.
         /// </summary>
         /// <param name="catalog">The regression catalog trainer object.</param>
-        /// <param name="labelColumnName">The name of the label column.</param>
-        /// <param name="featureColumnName">The name of the feature column.</param>
+        /// <param name="labelColumnName">The name of the label column. The column data must be <see cref="System.Single"/></param>
+        /// <param name="featureColumnName">The name of the feature column. The column data must be a known-sized vector of <see cref="System.Single"/></param>
         /// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
         /// <param name="l1Regularization">The L1 <a href='https://en.wikipedia.org/wiki/Regularization_(mathematics)'>regularization</a> hyperparameter. Higher values will tend to lead to more sparse model.</param>
         /// <param name="l2Regularization">The L2 weight for <a href='https://en.wikipedia.org/wiki/Regularization_(mathematics)'>regularization</a>.</param>
@@ -606,7 +606,7 @@ public static LbfgsPoissonRegressionTrainer LbfgsPoissonRegression(this Regressi
         }
 
         /// <summary>
-        /// Predict a target using a linear regression model trained with the <see cref="Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer"/> and advanced options.
+        /// Creates a <see cref="Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer"/>, which predicts a target using a linear regression model with advanced options.
         /// </summary>
         /// <param name="catalog">The regression catalog trainer object.</param>
         /// <param name="options">Trainer options.</param>

From 3826e506de4842d1a87c55aa52a9aae1be9874e0 Mon Sep 17 00:00:00 2001
From: Zeeshan Siddiqui <mzs@microsoft.com>
Date: Fri, 19 Apr 2019 18:08:22 -0700
Subject: [PATCH 2/2] PR feedback.

---
 .../Standard/PoissonRegression/PoissonRegression.cs       | 7 ++++---
 .../StandardTrainersCatalog.cs                            | 8 ++++----
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/Microsoft.ML.StandardTrainers/Standard/PoissonRegression/PoissonRegression.cs b/src/Microsoft.ML.StandardTrainers/Standard/PoissonRegression/PoissonRegression.cs
index e64ace20af..8eced48dd1 100644
--- a/src/Microsoft.ML.StandardTrainers/Standard/PoissonRegression/PoissonRegression.cs
+++ b/src/Microsoft.ML.StandardTrainers/Standard/PoissonRegression/PoissonRegression.cs
@@ -49,8 +49,8 @@ namespace Microsoft.ML.Trainers
     /// ]]>
     /// </format>
     /// </remarks>
-    /// <seealso cref="Microsoft.ML.StandardTrainersCatalog.LbfgsPoissonRegression(Microsoft.ML.RegressionCatalog.RegressionTrainers,System.String,System.String,System.String,System.Single,System.Single,System.Single,System.Int32,System.Boolean)"/>
-    /// <seealso cref="Microsoft.ML.StandardTrainersCatalog.LbfgsPoissonRegression(Microsoft.ML.RegressionCatalog.RegressionTrainers,Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer.Options)"/>
+    /// <seealso cref="StandardTrainersCatalog.LbfgsPoissonRegression(RegressionCatalog.RegressionTrainers, string, string, string, float, float, float, int, bool)"/>
+    /// <seealso cref="StandardTrainersCatalog.LbfgsPoissonRegression(RegressionCatalog.RegressionTrainers, LbfgsPoissonRegressionTrainer.Options)"/>
     /// <seealso cref="Options"/>
     public sealed class LbfgsPoissonRegressionTrainer : LbfgsTrainerBase<LbfgsPoissonRegressionTrainer.Options, RegressionPredictionTransformer<PoissonRegressionModelParameters>, PoissonRegressionModelParameters>
     {
@@ -60,7 +60,8 @@ public sealed class LbfgsPoissonRegressionTrainer : LbfgsTrainerBase<LbfgsPoisso
         internal const string Summary = "Poisson Regression assumes the unknown function, denoted Y has a Poisson distribution.";
 
         /// <summary>
-        /// Options for the <see cref="LbfgsPoissonRegressionTrainer"/>.
+        /// Options for the <see cref="LbfgsPoissonRegressionTrainer"/> as used in
+        /// [LbfgsPoissonRegression(Options)](xref:Microsoft.ML.StandardTrainersCatalog.LbfgsPoissonRegression(Microsoft.ML.RegressionCatalog.RegressionTrainers,Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer.Options)).
         /// </summary>
         public sealed class Options : OptionsBase
         {
diff --git a/src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs b/src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs
index 601950b948..09477bc6ac 100644
--- a/src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs
+++ b/src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs
@@ -573,11 +573,11 @@ public static LbfgsLogisticRegressionBinaryTrainer LbfgsLogisticRegression(this
         }
 
         /// <summary>
-        /// Creates a <see cref="Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer"/>, which predicts a target using a linear regression model.
+        /// Create <see cref="LbfgsPoissonRegressionTrainer"/>, which predicts a target using a linear regression model.
         /// </summary>
         /// <param name="catalog">The regression catalog trainer object.</param>
-        /// <param name="labelColumnName">The name of the label column. The column data must be <see cref="System.Single"/></param>
-        /// <param name="featureColumnName">The name of the feature column. The column data must be a known-sized vector of <see cref="System.Single"/></param>
+        /// <param name="labelColumnName">The name of the label column. The column data must be <see cref="System.Single"/>.</param>
+        /// <param name="featureColumnName">The name of the feature column. The column data must be a known-sized vector of <see cref="System.Single"/>.</param>
         /// <param name="exampleWeightColumnName">The name of the example weight column (optional).</param>
         /// <param name="l1Regularization">The L1 <a href='https://en.wikipedia.org/wiki/Regularization_(mathematics)'>regularization</a> hyperparameter. Higher values will tend to lead to more sparse model.</param>
         /// <param name="l2Regularization">The L2 weight for <a href='https://en.wikipedia.org/wiki/Regularization_(mathematics)'>regularization</a>.</param>
@@ -606,7 +606,7 @@ public static LbfgsPoissonRegressionTrainer LbfgsPoissonRegression(this Regressi
         }
 
         /// <summary>
-        /// Creates a <see cref="Microsoft.ML.Trainers.LbfgsPoissonRegressionTrainer"/>, which predicts a target using a linear regression model with advanced options.
+        /// Create <see cref="LbfgsPoissonRegressionTrainer"/> using advanced options, which predicts a target using a linear regression model.
         /// </summary>
         /// <param name="catalog">The regression catalog trainer object.</param>
         /// <param name="options">Trainer options.</param>