Towards #3204 - documentation for ApproximatedKernelMappingEstimator (#3377)

* Documentation for ApproximatedKernelMappingEstimator

* Address code review comments

* Address Shahab's comments

Author: yaeldMS

src/Microsoft.ML.Transforms/KernelCatalog.cs

@@ -13,15 +13,20 @@ namespace Microsoft.ML
     public static class KernelExpansionCatalog
     {
         /// <summary>
-        /// Takes column filled with a vector of floats and maps its to a random low-dimensional feature space.
+        /// Create an <see cref="ApproximatedKernelMappingEstimator"/> that maps input vectors to a low dimensional
+        /// feature space where inner products approximate a shift-invariant kernel function.
         /// </summary>
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="outputColumnName">Name of the column resulting from the transformation of <paramref name="inputColumnName"/>.</param>
-        /// <param name="inputColumnName">Name of column to transform. If set to <see langword="null"/>, the value of the <paramref name="outputColumnName"/> will be used as source.</param>
-        /// <param name="rank">The number of random Fourier features to create.</param>
-        /// <param name="useCosAndSinBases">If <see langword="true"/>, use both of cos and sin basis functions to create two features for every random Fourier frequency.
-        /// Otherwise, only cos bases would be used.</param>
-        /// <param name="generator">Which fourier generator to use.</param>
+        /// <param name="inputColumnName">Name of column to transform. If set to <see langword="null"/>,
+        /// the value of the <paramref name="outputColumnName"/> will be used as source.
+        /// The data type on this column should be a known-sized vector of <see cref="System.Single"/>.</param>
+        /// <param name="rank">The dimension of the feature space to map the input to.</param>
+        /// <param name="useCosAndSinBases">If <see langword="true"/>, use both of cos and sin basis functions to create
+        /// two features for every random Fourier frequency. Otherwise, only cos bases would be used. Note that if set
+        /// to <see langword="true"/>, the dimension of the output feature space will be 2*<paramref name="rank"/>.</param>
+        /// <param name="generator">The argument that indicates which kernel to use. The two available implementations
+        /// are <see cref="GaussianKernel"/> and <see cref="LaplacianKernel"/>.</param>
         /// <param name="seed">The seed of the random number generator for generating the new features (if unspecified, the global random is used).</param>
         /// <example>
         /// <format type="text/markdown">
@@ -41,7 +46,8 @@ public static ApproximatedKernelMappingEstimator ApproximatedKernelMap(this Tran
                 new[] { new ApproximatedKernelMappingEstimator.ColumnOptions(outputColumnName, rank, useCosAndSinBases, inputColumnName, generator, seed) });
 
         /// <summary>
-        /// Takes columns filled with a vector of floats and maps its to a random low-dimensional feature space.
+        /// Create an <see cref="ApproximatedKernelMappingEstimator"/> that maps input vectors to a low dimensional
+        /// feature space where inner products approximate a shift-invariant kernel function.
         /// </summary>
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="columns">The input columns to use for the transformation.</param>

src/Microsoft.ML.Transforms/RandomFourierFeaturizing.cs

@@ -29,11 +29,7 @@
 namespace Microsoft.ML.Transforms
 {
     /// <summary>
-    /// Maps vector columns to a feature space where the inner products approximate a user specified shift-invariant kernel.
-    /// The kernel is indicated by specifying a <see cref="KernelBase"/> instance. The available implementations
-    /// are <see cref="GaussianKernel"/> and <see cref="LaplacianKernel"/>.
-    /// This transformation is based on this paper by
-    /// <a href="http://pages.cs.wisc.edu/~brecht/papers/07.rah.rec.nips.pdf">Rahimi and Recht</a>.
+    /// <see cref="ITransformer"/> resulting from fitting an <see cref="ApproximatedKernelMappingEstimator"/>.
     /// </summary>
     public sealed class ApproximatedKernelTransformer : OneToOneTransformerBase
     {
@@ -605,6 +601,27 @@ private void TransformFeatures(in VBuffer<float> src, ref VBuffer<float> dst, Tr
     /// <summary>
     /// Maps vector columns to a low -dimensional feature space.
     /// </summary>
+    /// <remarks>
+    /// <format type="text/markdown"><![CDATA[
+    ///
+    /// ###  Estimator Characteristics
+    /// |  |  |
+    /// | -- | -- |
+    /// | Does this estimator need to look at the data to train its parameters? | Yes |
+    /// | Input column data type | Known-sized vector of <xref:System.Single> |
+    /// | Output column data type | Known-sized vector of <xref:System.Single> |
+    ///
+    /// The resulting <xref:Microsoft.ML.Transforms.ApproximatedKernelTransformer> creates a new column, named as specified in
+    /// the output column name parameters, where each input vector is mapped to a feature space where inner products
+    /// approximate one of two shift-invariant kernel functions: The Gaussian kernel, or the Laplacian kernel.
+    /// By mapping features to a space that approximate non-linear kernels, linear methods can be used to approximate
+    /// more complex kernel SVM models.
+    /// This mapping is based on the paper [Random Features for Large-Scale Kernel Machines](http://pages.cs.wisc.edu/~brecht/papers/07.rah.rec.nips.pdf)
+    /// by Rahimi and Recht.
+    /// ]]></format>
+    /// </remarks>
+    /// <seealso cref="KernelExpansionCatalog.ApproximatedKernelMap(TransformsCatalog, ColumnOptions[])"/>
+    /// <seealso cref="KernelExpansionCatalog.ApproximatedKernelMap(TransformsCatalog, string, string, int, bool, KernelBase, int?)"/>
     public sealed class ApproximatedKernelMappingEstimator : IEstimator<ApproximatedKernelTransformer>
     {
         [BestFriend]