Improved documentation for LdSvmTrainer (dotnet#4934)

* Improved documentation for LdSvmTrainer

* Minor rewording

Author: najeeb-kazmi

src/Microsoft.ML.StandardTrainers/LdSvm/LdSvmTrainer.cs

@@ -26,11 +26,42 @@
 namespace Microsoft.ML.Trainers
 {
     /// <summary>
-    /// Non-Linear SVM that implements Local Deep SVM based on paper :
-    /// C. Jose, P. Goyal, P. Aggrwal, and M. Varma, Local deep
-    /// kernel learning for efficient non-linear svm prediction, in ICML, 2013.
-    /// http://research.microsoft.com/en-us/um/people/manik/code/LDKL/download.html
+    /// The <see cref="IEstimator{TTransformer}"/> to predict a target using a non-linear binary classification model
+    /// trained with Local Deep SVM.
     /// </summary>
+    /// <remarks>
+    /// <format type="text/markdown"><![CDATA[
+    /// To create this trainer, use [LdSvm](xref:Microsoft.ML.StandardTrainersCatalog.LdSvm(BinaryClassificationCatalog.BinaryClassificationTrainers, string, string, string, int, int, bool, bool))
+    /// or [LdSvm(Options)](xref:Microsoft.ML.StandardTrainersCatalog.LdSvm(BinaryClassificationCatalog.BinaryClassificationTrainers, LdSvmTrainer.Options)).
+    ///
+    /// [!include[io](~/../docs/samples/docs/api-reference/io-columns-binary-classification-no-prob.md)]
+    ///
+    /// ### Trainer Characteristics
+    /// |  |  |
+    /// | -- | -- |
+    /// | Machine learning task | Binary classification |
+    /// | Is normalization required? | Yes |
+    /// | Is caching required? | No |
+    /// | Required NuGet in addition to Microsoft.ML | None |
+    /// | Exportable to ONNX | No |
+    ///
+    /// ### Training Algorithm Details
+    /// Local Deep SVM (LD-SVM) is a generalization of Localized Multiple Kernel Learning for non-linear SVM. Multiple kernel methods learn a different
+    /// kernel, and hence a different classifier, for each point in the feature space. The prediction time cost for multiple kernal methods can be prohibitively
+    /// expensive for large training sets because it is proportional to the number of support vectors, and these grow linearly with the size of the training
+    /// set. LD-SVM reduces the prediction cost by learning a tree-based local feature embedding that is high dimensional and sparse, efficiently encoding
+    /// non-linearities. Using LD-SVM, the prediction cost grows logarithmically with the size of the training set, rather than linearly, with a tolerable loss
+    /// in classification accuracy.
+    ///
+    /// Local Deep SVM is an implementation of the algorithm decribed in [C. Jose, P. Goyal, P. Aggrwal, and M. Varma, Local Deep
+    /// Kernel Learning for Efficient Non-linear SVM Prediction, ICML, 2013](http://proceedings.mlr.press/v28/jose13.pdf).
+    ///
+    /// Check the See Also section for links to usage examples.
+    /// ]]>
+    /// </format>
+    /// </remarks>
+    /// <seealso cref="StandardTrainersCatalog.LdSvm(BinaryClassificationCatalog.BinaryClassificationTrainers, LdSvmTrainer.Options)"/>
+    /// <seealso cref="StandardTrainersCatalog.LdSvm(BinaryClassificationCatalog.BinaryClassificationTrainers, string, string, string, int, int, bool, bool)"/>
     public sealed class LdSvmTrainer : TrainerEstimatorBase<BinaryPredictionTransformer<LdSvmModelParameters>, LdSvmModelParameters>
     {
         internal const string LoadNameValue = "LDSVM";

src/Microsoft.ML.StandardTrainers/Standard/Online/LinearSvm.cs

@@ -52,7 +52,7 @@ namespace Microsoft.ML.Trainers
     /// That is the same as the sign of the feautures' weighted sum, i.e. $\sum_{i = 0}^{D-1} \left(w_i * f_i \right) + b$, where $w_0, w_1,..., w_{D-1}$
     /// are the weights computed by the algorithm, and $b$ is the bias computed by the algorithm.
     ///
-    /// This algorithm implemented is the PEGASOS method, which alternates between stochastic gradient descent steps and projection steps,
+    /// Linear SVM implements the PEGASOS method, which alternates between stochastic gradient descent steps and projection steps,
     /// introduced in [this paper](http://ttic.uchicago.edu/~shai/papers/ShalevSiSr07.pdf) by Shalev-Shwartz, Singer and Srebro.
     ///
     /// Check the See Also section for links to usage examples.

src/Microsoft.ML.StandardTrainers/StandardTrainersCatalog.cs

@@ -851,7 +851,7 @@ public static LinearSvmTrainer LinearSvm(this BinaryClassificationCatalog.Binary
         }
 
         /// <summary>
-        /// Create <see cref="PriorTrainer"/>, which predict a target using a binary classification model.
+        /// Create <see cref="PriorTrainer"/>, which predicts a target using a binary classification model.
         /// </summary>
         /// <remarks>
         /// This trainer uses the proportion of a label in the training set as the probability of that label.
@@ -875,15 +875,21 @@ public static PriorTrainer Prior(this BinaryClassificationCatalog.BinaryClassifi
         }
 
         /// <summary>
-        /// Create <see cref="LdSvmTrainer"/> with advanced options, which predicts a target using a Local Deep SVM model model.
+        /// Create <see cref="LdSvmTrainer"/> with advanced options, which predicts a target using a Local Deep SVM model.
         /// </summary>
         /// <param name="catalog">The <see cref="BinaryClassificationCatalog"/>.</param>
         /// <param name="options">Trainer options.</param>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        ///  [!code-csharp[LdSvm](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/LdSvmWithOptions.cs)]
+        /// ]]></format>
+        /// </example>
         public static LdSvmTrainer LdSvm(this BinaryClassificationCatalog.BinaryClassificationTrainers catalog, LdSvmTrainer.Options options)
             => new LdSvmTrainer(catalog.GetEnvironment(), options);
 
         /// <summary>
-        /// Create <see cref="LdSvmTrainer"/>, which predicts a target using a Local Deep SVM model model.
+        /// Create <see cref="LdSvmTrainer"/>, which predicts a target using a Local Deep SVM model.
         /// </summary>
         /// <param name="catalog">The <see cref="BinaryClassificationCatalog"/>.</param>
         /// <param name="labelColumnName">The name of the label column.</param>
@@ -893,7 +899,12 @@ public static LdSvmTrainer LdSvm(this BinaryClassificationCatalog.BinaryClassifi
         /// <param name="treeDepth">The depth of a Local Deep SVM tree.</param>
         /// <param name="useBias">Indicates if the model should have a bias term.</param>
         /// <param name="useCachedData">Indicates whether we should iterate over the data using a cache.</param>
-        /// <returns></returns>
+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        ///  [!code-csharp[LdSvm](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Trainers/BinaryClassification/LdSvm.cs)]
+        /// ]]></format>
+        /// </example>
         public static LdSvmTrainer LdSvm(this BinaryClassificationCatalog.BinaryClassificationTrainers catalog,
             string labelColumnName = DefaultColumnNames.Label,
             string featureColumnName = DefaultColumnNames.Features,