Improve C# documentation (#1154)

Added missing C# documentation according to the Javadoc (#1136).

Internal work item: https://task.ms/aii/53908

src/csharp/Adapters.cs

@@ -12,34 +12,39 @@ namespace Microsoft.ML.OnnxRuntimeGenAI
     public class Adapters : SafeHandle
     {
         /// <summary>
-        /// Creates a container for adapters
-        /// used to load, unload and hold them.
-        /// Throws on error.
+        /// Constructs an Adapters object with the given model.
         /// </summary>
         /// <param name="model">Reference to a loaded model</param>
-        /// <returns>new Adapters object</returns>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public Adapters(Model model) : base(IntPtr.Zero, true)
         {
             Result.VerifySuccess(NativeMethods.OgaCreateAdapters(model.Handle, out handle));
         }
 
         /// <summary>
-        /// Method that loads adapter data and assigns it a nmae that
-        /// it can be referred to. Throws on error.
+        /// Loads the model adapter from the given adapter file path and adapter name.
         /// </summary>
-        /// <param name="adapterPath">file path to load</param>
-        /// <param name="adapterName">adapter name</param>
-        public void LoadAdapter(string adapterPath, string adapterName)
+        /// <param name="adapterPath">The path of the adapter.</param>
+        /// <param name="adapterName">A unique user supplied adapter identifier.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
+        public void LoadAdapter(string adapterFilePath, string adapterName)
         {
             Result.VerifySuccess(NativeMethods.OgaLoadAdapter(handle,
-                StringUtils.ToUtf8(adapterPath), StringUtils.ToUtf8(adapterName)));
+                StringUtils.ToUtf8(adapterFilePath), StringUtils.ToUtf8(adapterName)));
         }
 
         /// <summary>
-        /// Unload the adatper that was loaded by the LoadAdapter method.
-        /// Throws on error.
+        /// Unloads the adapter with the given identifier from the previosly loaded adapters. If the
+        /// adapter is not found, or if it cannot be unloaded (when it is in use), an error is returned.
         /// </summary>
         /// <param name="adapterName"></param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void UnloadAdapter(string adapterName)
         {
             Result.VerifySuccess(NativeMethods.OgaUnloadAdapter(handle, StringUtils.ToUtf8(adapterName)));
@@ -48,7 +53,7 @@ public void UnloadAdapter(string adapterName)
         internal IntPtr Handle { get { return handle; } }
 
         /// <summary>
-        /// Implement SafeHandle override
+        /// Implement SafeHandle override.
         /// </summary>
         public override bool IsInvalid => handle == IntPtr.Zero;
 

src/csharp/Config.cs

@@ -5,29 +5,65 @@
 
 namespace Microsoft.ML.OnnxRuntimeGenAI
 {
+    /// <summary>
+    /// Use Config to set the ORT execution providers (EPs) and their options. The EPs are applied based on
+    /// insertion order.
+    /// </summary>
     public class Config : IDisposable
     {
         private IntPtr _configHandle;
         private bool _disposed = false;
+
+        /// <summary>
+        /// Creates a Config from the given configuration directory.
+        /// </summary>
+        /// <param name="modelPath">The path to the configuration directory.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public Config(string modelPath)
         {
             Result.VerifySuccess(NativeMethods.OgaCreateConfig(StringUtils.ToUtf8(modelPath), out _configHandle));
         }
 
         internal IntPtr Handle { get { return _configHandle; } }
+
+        /// <summary>
+        /// Clear the list of providers in the config.
+        /// </summary>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void ClearProviders()
         {
             Result.VerifySuccess(NativeMethods.OgaConfigClearProviders(_configHandle));
         }
 
-        public void AppendProvider(string provider)
+        /// <summary>
+        /// Add the provider at the end of the list of providers in the given config if it doesn't already
+        /// exist. If it already exists, does nothing.
+        /// </summary>
+        /// <param name="providerName">Name of the provider</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
+        public void AppendProvider(string providerName)
         {
-            Result.VerifySuccess(NativeMethods.OgaConfigAppendProvider(_configHandle, StringUtils.ToUtf8(provider)));
+            Result.VerifySuccess(NativeMethods.OgaConfigAppendProvider(_configHandle, StringUtils.ToUtf8(providerName)));
         }
 
-        public void SetProviderOption(string provider, string option, string value)
+        /// <summary>
+        /// Set a provider option.
+        /// </summary>
+        /// <param name="providerName">Name of the provider</param>
+        /// <param name="optionKey">Name of the option</param>
+        /// <param name="optionValue">Value of the option</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
+        public void SetProviderOption(string providerName, string optionKey, string optionValue)
         {
-            Result.VerifySuccess(NativeMethods.OgaConfigSetProviderOption(_configHandle, StringUtils.ToUtf8(provider), StringUtils.ToUtf8(option), StringUtils.ToUtf8(value)));
+            Result.VerifySuccess(NativeMethods.OgaConfigSetProviderOption(_configHandle, StringUtils.ToUtf8(providerName), StringUtils.ToUtf8(optionKey), StringUtils.ToUtf8(optionValue)));
         }
 
         ~Config()

src/csharp/Exceptions.cs

@@ -5,13 +5,14 @@
 
 namespace Microsoft.ML.OnnxRuntimeGenAI
 {
+    /// <summary>
+    /// An exception which contains the error message and code produced by the native layer.
+    /// </summary>
     public class OnnxRuntimeGenAIException: Exception
     {
         internal OnnxRuntimeGenAIException(string message)
             :base(message)
         {
         }
     }
-
-
 }

src/csharp/Generator.cs

@@ -5,21 +5,44 @@
 
 namespace Microsoft.ML.OnnxRuntimeGenAI
 {
+    /// <summary>
+    /// The Generator class generates output using a model and generator parameters.
+    /// </summary>
     public class Generator : IDisposable
     {
         private IntPtr _generatorHandle;
         private bool _disposed = false;
 
+        /// <summary>
+        /// Constructs a Generator object with the given model and generator parameters.
+        /// <param name="model">The model to use.</param>
+        /// <param name="generatorParams">The generator parameters.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public Generator(Model model, GeneratorParams generatorParams)
         {
             Result.VerifySuccess(NativeMethods.OgaCreateGenerator(model.Handle, generatorParams.Handle, out _generatorHandle));
         }
 
+        /// <summary>
+        /// Checks if the generation process is done.
+        /// </summary>
+        /// <returns>
+        /// True if the generation process is done, false otherwise.
+        /// </returns>
         public bool IsDone()
         {
             return NativeMethods.OgaGenerator_IsDone(_generatorHandle) != 0;
         }
 
+        /// <summary>
+        /// Appends tokens to the generator.
+        /// </summary>
+        /// <param name="inputIDs">The tokens to append.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void AppendTokens(ReadOnlySpan<int> inputIDs)
         {
             unsafe
@@ -31,26 +54,50 @@ public void AppendTokens(ReadOnlySpan<int> inputIDs)
             }
         }
 
+        /// <summary>
+        /// Appends token sequences to the generator.
+        /// </summary>
+        /// <param name="sequences">The sequences to append.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void AppendTokenSequences(Sequences sequences)
         {
             Result.VerifySuccess(NativeMethods.OgaGenerator_AppendTokenSequences(_generatorHandle, sequences.Handle));
         }
 
+        /// <summary>
+        /// Computes the logits from the model based on the input ids and the past state. The computed
+        /// logits are stored in the generator.
+        /// </summary>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void GenerateNextToken()
         {
             Result.VerifySuccess(NativeMethods.OgaGenerator_GenerateNextToken(_generatorHandle));
         }
 
         /// <summary>
-        /// Rewinds the generator to the given newLength.
-        /// Throw on error
+        /// Rewinds the generator to the given length. This is useful when the user wants to rewind the
+        /// generator to a specific length and continue generating from that point.
         /// </summary>
-        /// <param name="newLength"></param>
+        /// <param name="newLength">The desired length in tokens after rewinding.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void RewindTo(ulong newLength)
         {
             Result.VerifySuccess(NativeMethods.OgaGenerator_RewindTo(_generatorHandle, (UIntPtr)newLength));
         }
 
+        /// <summary>
+        /// Retrieves a sequence of token ids for the specified sequence index.
+        /// </summary>
+        /// <param name="index">The index of the sequence.</param>
+        /// <returns>
+        /// A ReadOnlySpan of integers with the sequence token ids.
+        /// </returns>
         public ReadOnlySpan<int> GetSequence(ulong index)
         {
             ulong sequenceLength = NativeMethods.OgaGenerator_GetSequenceCount(_generatorHandle, (UIntPtr)index).ToUInt64();
@@ -62,25 +109,29 @@ public ReadOnlySpan<int> GetSequence(ulong index)
         }
 
         /// <summary>
-        /// Fetches and returns the output tensor with the given name.
-        /// Throw on error
+        /// Returns a copy of the model output identified by the given name as a Tensor.
         /// </summary>
-        /// <param name="outputName"></param>
-        /// <returns>a disposable instance of Tensor</returns>
-        public Tensor GetOutput(string outputName)
+        /// <param name="name">The name of the output needed.</param>
+        /// <returns>A disposable instance of Tensor</returns>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
+        public Tensor GetOutput(string name)
         {
             Result.VerifySuccess(NativeMethods.OgaGenerator_GetOutput(_generatorHandle,
-                                                                      StringUtils.ToUtf8(outputName),
+                                                                      StringUtils.ToUtf8(name),
                                                                       out IntPtr outputTensor));
             return new Tensor(outputTensor);
         }
 
         /// <summary>
-        /// Activates one of the loaded adapters.
-        /// Throws on error.
+        /// Sets the adapter with the given adapter name as active.
         /// </summary>
-        /// <param name="adapters">Adapters container</param>
-        /// <param name="adapterName">adapter name that was previously loaded</param>
+        /// <param name="adapters">The adapters container.</param>
+        /// <param name="adapterName">The adapter name that was previously loaded.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void SetActiveAdapter(Adapters adapters, string adapterName)
         {
             Result.VerifySuccess(NativeMethods.OgaSetActiveAdapter(_generatorHandle,

src/csharp/GeneratorParams.cs

@@ -8,37 +8,86 @@
 
 namespace Microsoft.ML.OnnxRuntimeGenAI
 {
+    /// <summary>
+    /// Represents the parameters used for generating sequences with a model.
+    /// </summary>
     public class GeneratorParams : IDisposable
     {
         private IntPtr _generatorParamsHandle;
         private bool _disposed = false;
+
+        /// <summary>
+        /// Creates a GeneratorParams from the given model.
+        /// </summary>
+        /// <param name="model">The model to use.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public GeneratorParams(Model model)
         {
             Result.VerifySuccess(NativeMethods.OgaCreateGeneratorParams(model.Handle, out _generatorParamsHandle));
         }
 
         internal IntPtr Handle { get { return _generatorParamsHandle; } }
 
+        /// <summary>
+        /// Set seach option with double value.
+        /// </summary>
+        /// <param name="searchOption">The option name</param>
+        /// <param name="value">The option value</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void SetSearchOption(string searchOption, double value)
         {
             Result.VerifySuccess(NativeMethods.OgaGeneratorParamsSetSearchNumber(_generatorParamsHandle, StringUtils.ToUtf8(searchOption), value));
         }
 
+        /// <summary>
+        /// Set seach option with boolean value.
+        /// </summary>
+        /// <param name="searchOption">The option name</param>
+        /// <param name="value">The option value</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void SetSearchOption(string searchOption, bool value)
         {
             Result.VerifySuccess(NativeMethods.OgaGeneratorParamsSetSearchBool(_generatorParamsHandle, StringUtils.ToUtf8(searchOption), value));
         }
 
+        /// <summary>
+        /// Try graph capture.
+        /// </summary>
+        /// <param name="maxBatchSize">The max batch size</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void TryGraphCaptureWithMaxBatchSize(int maxBatchSize)
         {
             Result.VerifySuccess(NativeMethods.OgaGeneratorParamsTryGraphCaptureWithMaxBatchSize(_generatorParamsHandle, maxBatchSize));
         }
 
+        /// <summary>
+        /// Add a Tensor as a model input.
+        /// </summary>
+        /// <param name="name">The name of the model input the tensor will provide.</param>
+        /// <param name="value">The tensor value.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void SetModelInput(string name, Tensor value)
         {
             Result.VerifySuccess(NativeMethods.OgaGeneratorParamsSetModelInput(_generatorParamsHandle, StringUtils.ToUtf8(name), value.Handle));
         }
 
+        /// <summary>
+        /// Add a NamedTensors as a model input.
+        /// </summary>
+        /// <param name="namedTensors">The NamedTensors value.</param>
+        /// <exception cref="OnnxRuntimeGenAIException">
+        /// Thrown when the call to the GenAI native API fails.
+        /// </exception>
         public void SetInputs(NamedTensors namedTensors)
         {
             Result.VerifySuccess(NativeMethods.OgaGeneratorParamsSetInputs(_generatorParamsHandle, namedTensors.Handle));

src/csharp/Images.cs

@@ -6,6 +6,9 @@
 
 namespace Microsoft.ML.OnnxRuntimeGenAI
 {
+    /// <summary>
+    /// This class can load images from the given path and prepare them for processing.
+    /// </summary>
     public class Images : IDisposable
     {
         private IntPtr _imagesHandle;
@@ -18,7 +21,7 @@ private Images(IntPtr imagesHandle)
 
         internal IntPtr Handle { get { return _imagesHandle; } }
 
-        public static Images Load(string[] imagePaths)
+        private static Images Load(string[] imagePaths)
         {
             Result.VerifySuccess(NativeMethods.OgaCreateStringArray(out IntPtr stringArray));
             foreach (string imagePath in imagePaths)