Update OnnxTransformer Docs (#5296)

Update OnnxTransformer Docs

Author: antoniovs1029

src/Microsoft.ML.OnnxTransformer/OnnxCatalog.cs

@@ -15,6 +15,8 @@ public static class OnnxCatalog
         /// <summary>
         /// Create a <see cref="OnnxScoringEstimator"/>, which applies a pre-trained Onnx model to the input column.
         /// Input/output columns are determined based on the input/output columns of the provided ONNX model.
+        /// Please refer to <see cref="OnnxScoringEstimator"/> to learn more about the necessary dependencies,
+        /// and how to run it on a GPU.
         /// </summary>
         /// <remarks>
         /// The name/type of input columns must exactly match name/type of the ONNX model inputs.
@@ -40,14 +42,19 @@ public static OnnxScoringEstimator ApplyOnnxModel(this TransformsCatalog catalog
         /// <summary>
         /// Create a <see cref="OnnxScoringEstimator"/>, which applies a pre-trained Onnx model to the input column.
         /// Input/output columns are determined based on the input/output columns of the provided ONNX model.
+        /// Please refer to <see cref="OnnxScoringEstimator"/> to learn more about the necessary dependencies,
+        /// and how to run it on a GPU.
         /// </summary>
         /// <remarks>
         /// The name/type of input columns must exactly match name/type of the ONNX model inputs.
         /// The name/type of the produced output columns will match name/type of the ONNX model outputs.
         /// </remarks>
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="modelFile">The path of the file containing the ONNX model.</param>
-        /// <param name="shapeDictionary">ONNX shape should be used to over those loaded from <paramref name="modelFile"/>.</param>
+        /// <param name="shapeDictionary">ONNX shapes to be used over those loaded from <paramref name="modelFile"/>.
+        /// For keys use names as stated in the ONNX model, e.g. "input". Stating the shapes with this parameter
+        /// is particullarly useful for working with variable dimension inputs and outputs.
+        /// </param>
         /// <param name="gpuDeviceId">Optional GPU device ID to run execution on, <see langword="null" /> to run on CPU.</param>
         /// <param name="fallbackToCpu">If GPU error, raise exception or fallback to CPU.</param>
         /// <example>
@@ -67,6 +74,8 @@ public static OnnxScoringEstimator ApplyOnnxModel(this TransformsCatalog catalog
 
         /// <summary>
         /// Create a <see cref="OnnxScoringEstimator"/>, which applies a pre-trained Onnx model to the <paramref name="inputColumnName"/> column.
+        /// Please refer to <see cref="OnnxScoringEstimator"/> to learn more about the necessary dependencies,
+        /// and how to run it on a GPU.
         /// </summary>
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="outputColumnName">The output column resulting from the transformation.</param>
@@ -92,12 +101,17 @@ public static OnnxScoringEstimator ApplyOnnxModel(this TransformsCatalog catalog
 
         /// <summary>
         /// Create a <see cref="OnnxScoringEstimator"/>, which applies a pre-trained Onnx model to the <paramref name="inputColumnName"/> column.
+        /// Please refer to <see cref="OnnxScoringEstimator"/> to learn more about the necessary dependencies,
+        /// and how to run it on a GPU.
         /// </summary>
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="outputColumnName">The output column resulting from the transformation.</param>
         /// <param name="inputColumnName">The input column.</param>
         /// <param name="modelFile">The path of the file containing the ONNX model.</param>
-        /// <param name="shapeDictionary">ONNX shape should be used to over those loaded from <paramref name="modelFile"/>.</param>
+        /// <param name="shapeDictionary">ONNX shapes to be used over those loaded from <paramref name="modelFile"/>.
+        /// For keys use names as stated in the ONNX model, e.g. "input". Stating the shapes with this parameter
+        /// is particullarly useful for working with variable dimension inputs and outputs.
+        /// </param>
         /// <param name="gpuDeviceId">Optional GPU device ID to run execution on, <see langword="null" /> to run on CPU.</param>
         /// <param name="fallbackToCpu">If GPU error, raise exception or fallback to CPU.</param>
         /// <example>
@@ -119,6 +133,8 @@ public static OnnxScoringEstimator ApplyOnnxModel(this TransformsCatalog catalog
 
         /// <summary>
         /// Create a <see cref="OnnxScoringEstimator"/>, which applies a pre-trained Onnx model to the <paramref name="inputColumnNames"/> columns.
+        /// Please refer to <see cref="OnnxScoringEstimator"/> to learn more about the necessary dependencies,
+        /// and how to run it on a GPU.
         /// </summary>
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="outputColumnNames">The output columns resulting from the transformation.</param>
@@ -137,12 +153,17 @@ public static OnnxScoringEstimator ApplyOnnxModel(this TransformsCatalog catalog
 
         /// <summary>
         /// Create a <see cref="OnnxScoringEstimator"/>, which applies a pre-trained Onnx model to the <paramref name="inputColumnNames"/> columns.
+        /// Please refer to <see cref="OnnxScoringEstimator"/> to learn more about the necessary dependencies,
+        /// and how to run it on a GPU.
         /// </summary>
         /// <param name="catalog">The transform's catalog.</param>
         /// <param name="outputColumnNames">The output columns resulting from the transformation.</param>
         /// <param name="inputColumnNames">The input columns.</param>
         /// <param name="modelFile">The path of the file containing the ONNX model.</param>
-        /// <param name="shapeDictionary">ONNX shape should be used to over those loaded from <paramref name="modelFile"/>.</param>
+        /// <param name="shapeDictionary">ONNX shapes to be used over those loaded from <paramref name="modelFile"/>.
+        /// For keys use names as stated in the ONNX model, e.g. "input". Stating the shapes with this parameter
+        /// is particullarly useful for working with variable dimension inputs and outputs.
+        /// </param>
         /// <param name="gpuDeviceId">Optional GPU device ID to run execution on, <see langword="null" /> to run on CPU.</param>
         /// <param name="fallbackToCpu">If GPU error, raise exception or fallback to CPU.</param>
         public static OnnxScoringEstimator ApplyOnnxModel(this TransformsCatalog catalog,

src/Microsoft.ML.OnnxTransformer/OnnxTransform.cs

@@ -36,6 +36,8 @@ namespace Microsoft.ML.Transforms.Onnx
 {
     /// <summary>
     /// <see cref="ITransformer"/> resulting from fitting an <see cref="OnnxScoringEstimator"/>.
+    /// Please refer to <see cref="OnnxScoringEstimator"/> to learn more about the necessary dependencies,
+    /// and how to run it on a GPU.
     /// </summary>
     public sealed class OnnxTransformer : RowToRowTransformerBase
     {
@@ -719,25 +721,24 @@ public NamedOnnxValue GetNamedOnnxValue()
     /// | Required NuGet in addition to Microsoft.ML | Microsoft.ML.OnnxTransformer (always),  either Microsoft.ML.OnnxRuntime 1.3.0 (for CPU processing) or Microsoft.ML.OnnxRuntime.Gpu 1.3.0 (for GPU processing if GPU is available) |
     /// | Exportable to ONNX | No |
     ///
+    /// To create this estimator use the following APIs:
+    /// [ApplyOnnxModel](xref:Microsoft.ML.OnnxCatalog.ApplyOnnxModel*)
+    ///
     /// Supports inferencing of models in ONNX 1.6 format (opset 11), using the [Microsoft.ML.OnnxRuntime](https://www.nuget.org/packages/Microsoft.ML.OnnxRuntime/) library.
     /// Models are scored on CPU if the project references Microsoft.ML.OnnxRuntime and on the GPU if the project references Microsoft.ML.OnnxRuntime.Gpu.
     /// Every project using the OnnxScoringEstimator must reference one of the above two packages.
     ///
     /// To run on a GPU, use the
     /// NuGet package [Microsoft.ML.OnnxRuntime.Gpu](https://www.nuget.org/packages/Microsoft.ML.OnnxRuntime.Gpu/) instead of the Microsoft.ML.OnnxRuntime nuget (which is for CPU processing). Microsoft.ML.OnnxRuntime.Gpu
     /// requires a [CUDA supported GPU](https://developer.nvidia.com/cuda-gpus#compute), the [CUDA 10.1 Toolkit](https://developer.nvidia.com/cuda-downloads), and [cuDNN 7.6.5](https://developer.nvidia.com/cudnn) (as indicated on [Onnxruntime's documentation](https://github.com/Microsoft/onnxruntime#default-gpu-cuda)).
-    /// Set parameter 'gpuDeviceId' to a valid non-negative integer. Typical device ID values are 0 or 1.
+    /// When creating the estimator through [ApplyOnnxModel](xref:Microsoft.ML.OnnxCatalog.ApplyOnnxModel*), set the parameter 'gpuDeviceId' to a valid non-negative integer. Typical device ID values are 0 or 1. If the GPU device isn't found but 'fallbackToCpu = true' then the estimator will run on the CPU. If the GPU device isn't found but 'fallbackToCpu = false' then the estimator will throw an exception
     ///
     /// The inputs and outputs of the ONNX models must be Tensor type. Sequence and Maps are not yet supported.
     ///
     /// OnnxRuntime works on Windows, MacOS and Ubuntu 16.04 Linux 64-bit platforms.
     /// Visit [ONNX Models](https://github.com/onnx/models) to see a list of readily available models to get started with.
     /// Refer to [ONNX](http://onnx.ai) for more information.
     ///
-    /// To create this estimator use the following:
-    /// [ApplyOnnxModel](xref:Microsoft.ML.OnnxCatalog.ApplyOnnxModel*)
-    ///
-    /// Check the See Also section for links to usage examples.
     /// ]]>
     /// </format>
     /// </remarks>