Documentation Improvements: Arrow API (#501)

Author: jescalada

README.md

@@ -262,6 +262,20 @@ devcontainer exec ./build_unix.sh
 devcontainer exec dotnet test csharp.test
 ```
 
+#### Code Formatting
+
+When formatting for the first time, you'll need to restore the formatter tool:
+
+```bash
+dotnet tool restore
+```
+
+Then, you can format any time with the following command which is also executed by the CI format checker:
+
+```bash
+dotnet jb cleanupcode "csharp" "csharp.test" "csharp.benchmark" --profile="Built-in: Reformat Code" --settings="ParquetSharp.DotSettings" --verbosity=WARN
+```
+
 ### Native
 
 Building ParquetSharp natively requires the following dependencies:

csharp/Arrow/ArrowReaderProperties.cs

@@ -4,10 +4,14 @@
 namespace ParquetSharp.Arrow
 {
     /// <summary>
-    /// Configures Arrow specific options for reading Parquet files
+    /// Configures Arrow specific options for reading Parquet files.
     /// </summary>
     public sealed class ArrowReaderProperties : IDisposable
     {
+        /// <summary>
+        /// Create a new <see cref="ArrowReaderProperties"/> with default values.
+        /// </summary>
+        /// <returns></returns>
         public static ArrowReaderProperties GetDefault()
         {
             return new ArrowReaderProperties(ExceptionInfo.Return<IntPtr>(ArrowReaderProperties_GetDefault));

csharp/Arrow/ArrowWriterProperties.cs

@@ -17,6 +17,9 @@ public enum WriterEngineVersion
             V2 = 1, // Full support for all nesting combinations
         }
 
+        /// <summary>
+        /// Create a new <see cref="ArrowWriterProperties"/> with default values.
+        /// </summary>
         public static ArrowWriterProperties GetDefault()
         {
             return new ArrowWriterProperties(ExceptionInfo.Return<IntPtr>(ArrowWriterProperties_GetDefault));

csharp/Arrow/FileReader.cs

@@ -122,9 +122,10 @@ public unsafe Apache.Arrow.Schema Schema
 
         /// <summary>
         /// Get a record batch reader for the file data
+        /// </summary>
         /// <param name="rowGroups">The indices of row groups to read data from</param>
         /// <param name="columns">The indices of columns to read, based on the schema</param>
-        /// </summary>
+        /// <returns>An Arrow array stream reader</returns>
         public unsafe IArrowArrayStream GetRecordBatchReader(
             int[]? rowGroups = null,
             int[]? columns = null)

csharp/Arrow/FileWriter.cs

@@ -185,7 +185,7 @@ public void WriteRecordBatch(RecordBatch recordBatch, long chunkSize = 1024 * 10
         /// multiple record batches to be written to the same row group.
         ///
         /// New row groups are started if the data reaches the MaxRowGroupLength configured
-        /// in the WriterProperties.
+        /// in the <see cref="WriterProperties"/>.
         /// </summary>
         /// <param name="recordBatch">The record batch to write</param>
         public void WriteBufferedRecordBatch(RecordBatch recordBatch)

csharp/Column.cs

@@ -12,13 +12,29 @@ public class Column
     {
 #pragma warning disable RS0027
 
+        /// <summary>
+        /// Create a column with the given properties.
+        /// </summary>
+        /// <param name="logicalSystemType">The <see cref="Type"/> of the column.</param>
+        /// <param name="name">The name of the column.</param>
+        /// <param name="logicalTypeOverride">Optional override for the logical type of the column.</param>
+        /// <exception cref="ArgumentNullException">Thrown if any of the arguments are null.</exception>
         public Column(Type logicalSystemType, string name, LogicalType? logicalTypeOverride = null)
             : this(logicalSystemType, name, logicalTypeOverride, GetTypeLength(logicalSystemType, logicalTypeOverride))
         {
             LogicalSystemType = logicalSystemType ?? throw new ArgumentNullException(nameof(logicalSystemType));
             Name = name ?? throw new ArgumentNullException(nameof(name));
         }
 
+        /// <summary>
+        /// Create a column with the given properties.
+        /// </summary>
+        /// <param name="logicalSystemType">The <see cref="Type"/> of the column.</param>
+        /// <param name="name">The name of the column.</param>
+        /// <param name="logicalTypeOverride">Optional override for the logical type of the column.</param>
+        /// <param name="length">The length of the column for decimal, Guid or Half types.</param>
+        /// <exception cref="ArgumentNullException">Thrown if any of the required arguments are null.</exception>
+        /// <exception cref="ArgumentException">Thrown if the length is set with an incompatible type.</exception>
         public Column(Type logicalSystemType, string name, LogicalType? logicalTypeOverride, int length)
         {
             var isDecimal = logicalSystemType == typeof(decimal) || logicalSystemType == typeof(decimal?);

csharp/ColumnWriter.cs

@@ -53,28 +53,76 @@ public long Close()
             return ExceptionInfo.Return<long>(Handle, ColumnWriter_Close);
         }
 
+        /// <summary>
+        /// Get the index of the column within the row group.
+        /// </summary>
         public int ColumnIndex { get; }
+        /// <summary>
+        /// Get the <see cref="ParquetSharp.LogicalTypeFactory"/> for the Parquet file writer.
+        /// </summary>
         public LogicalTypeFactory LogicalTypeFactory => RowGroupWriter.ParquetFileWriter.LogicalTypeFactory;
+        /// <summary>
+        /// Get the <see cref="ParquetSharp.LogicalWriteConverterFactory"/> for the Parquet file writer.
+        /// </summary>
         public LogicalWriteConverterFactory LogicalWriteConverterFactory => RowGroupWriter.ParquetFileWriter.LogicalWriteConverterFactory;
 
+        /// <summary>
+        /// Get the <see cref="ParquetSharp.ColumnDescriptor"/> for the column.
+        /// </summary>
         public ColumnDescriptor ColumnDescriptor => new(ExceptionInfo.Return<IntPtr>(Handle, ColumnWriter_Descr));
+        /// <summary>
+        /// Get the number of rows written to the column so far.
+        /// </summary>
         public long RowWritten => ExceptionInfo.Return<long>(Handle, ColumnWriter_Rows_Written);
+        /// <summary>
+        /// Get the physical type of the column.
+        /// </summary>
         public PhysicalType Type => ExceptionInfo.Return<PhysicalType>(Handle, ColumnWriter_Type);
+        /// <summary>
+        /// Get the <see cref="ParquetSharp.WriterProperties"/> for the column.
+        /// </summary>
         public WriterProperties WriterProperties => new(ExceptionInfo.Return<IntPtr>(Handle, ColumnWriter_Properties));
 
+        /// <summary>
+        /// Get the element <see cref="Type"/> of the data being written.
+        /// </summary>
         public abstract Type ElementType { get; }
+
+        /// <summary>
+        /// Apply a visitor to the column writer.
+        /// </summary>
+        /// <typeparam name="TReturn">The return type of the visitor.</typeparam>
+        /// <param name="visitor">The visitor instance.</param>
+        /// <returns>The result of the visitor operation.</returns>
         public abstract TReturn Apply<TReturn>(IColumnWriterVisitor<TReturn> visitor);
 
+        /// <summary>
+        /// Create a <see cref="LogicalColumnWriter"/>.
+        /// </summary>
+        /// <param name="bufferLength">The buffer length in bytes. Default is 4KB.</param>
+        /// <returns>A <see cref="LogicalColumnWriter"/> instance.</returns>
         public LogicalColumnWriter LogicalWriter(int bufferLength = 4 * 1024)
         {
             return LogicalColumnWriter.Create(this, bufferLength, elementTypeOverride: null);
         }
 
+        /// <summary>
+        /// Create a strongly-typed <see cref="LogicalColumnWriter"/> without an explicit element type override.
+        /// </summary>
+        /// <typeparam name="TElement">The type of the data to write.</typeparam>
+        /// <param name="bufferLength">The buffer length in bytes. Default is 4KB.</param>
+        /// <returns>A <see cref="LogicalColumnWriter"/> instance.</returns>
         public LogicalColumnWriter<TElement> LogicalWriter<TElement>(int bufferLength = 4 * 1024)
         {
             return LogicalColumnWriter.Create<TElement>(this, bufferLength, elementTypeOverride: null);
         }
 
+        /// <summary>
+        /// Create a strongly-typed <see cref="LogicalColumnWriter"/> with an explicit element type override.
+        /// </summary>
+        /// <typeparam name="TElement">The type of the data to write.</typeparam>
+        /// <param name="bufferLength">The buffer length in bytes. Default is 4KB.</param>
+        /// <returns>A <see cref="LogicalColumnWriter"/> instance.</returns>
         public LogicalColumnWriter<TElement> LogicalWriterOverride<TElement>(int bufferLength = 4 * 1024)
         {
             return LogicalColumnWriter.Create<TElement>(this, bufferLength, typeof(TElement));
@@ -181,26 +229,48 @@ protected IntPtr Handle
         internal readonly RowGroupWriter RowGroupWriter;
     }
 
-    /// <inheritdoc />
+    /// <summary>
+    /// Strongly-typed writer of physical Parquet values to a single column.
+    /// </summary>
+    /// <typeparam name="TValue">The data type of the column.</typeparam>
     public sealed class ColumnWriter<TValue> : ColumnWriter where TValue : unmanaged
     {
         internal ColumnWriter(IntPtr handle, RowGroupWriter rowGroupWriter, int columnIndex)
             : base(handle, rowGroupWriter, columnIndex)
         {
         }
 
+        /// <inheritdoc />
         public override Type ElementType => typeof(TValue);
 
+        /// <inheritdoc />
         public override TReturn Apply<TReturn>(IColumnWriterVisitor<TReturn> visitor)
         {
             return visitor.OnColumnWriter(this);
         }
 
+        /// <summary>
+        /// Write a batch of values to the column.
+        /// </summary>
+        /// <param name="values">The values to write.</param>
         public void WriteBatch(ReadOnlySpan<TValue> values)
         {
             WriteBatch(values.Length, null, null, values);
         }
 
+        /// <summary>
+        /// Write a batch of values to the column with optional definition and repetition levels.
+        /// </summary>
+        /// <param name="numValues">The number of values to write.</param>
+        /// <param name="defLevels">The definition levels for the values.</param>
+        /// <param name="repLevels">The repetition levels for the values.</param>
+        /// <param name="values">The values to write.</param>
+        /// <remarks>
+        /// The lengths of <paramref name="defLevels"/> and <paramref name="repLevels"/> must be at least <paramref name="numValues"/>.
+        /// </remarks>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="values"/> is null.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="numValues"/> is larger
+        /// than the length of <paramref name="defLevels"/> or <paramref name="repLevels"/>.</exception>
         public unsafe void WriteBatch(int numValues, ReadOnlySpan<short> defLevels, ReadOnlySpan<short> repLevels, ReadOnlySpan<TValue> values)
         {
             if (values == null) throw new ArgumentNullException(nameof(values));

csharp/FileDecryptionPropertiesBuilder.cs

@@ -148,7 +148,7 @@ public FileDecryptionPropertiesBuilder PlaintextFilesAllowed()
         /// <summary>
         /// Build the <see cref="FileDecryptionProperties"/> object.
         /// </summary>
-        /// <returns>A new <see cref="FileDecryptionProperties"/> object with the configured decryption properties.</returns>
+        /// <returns>The configured <see cref="FileDecryptionProperties"/> object.</returns>
         public FileDecryptionProperties Build() => new FileDecryptionProperties(ExceptionInfo.Return<IntPtr>(_handle, FileDecryptionPropertiesBuilder_Build));
 
         [DllImport(ParquetDll.Name)]

csharp/FileMetaData.cs

@@ -5,6 +5,9 @@
 
 namespace ParquetSharp
 {
+    /// <summary>
+    /// Metadata for a Parquet file. Includes information about the schema, row groups, versions, etc.
+    /// </summary>
     public sealed class FileMetaData : IEquatable<FileMetaData>, IDisposable
     {
         internal FileMetaData(IntPtr handle)
@@ -17,8 +20,15 @@ public void Dispose()
             _handle.Dispose();
         }
 
+        /// <summary>
+        /// Get the name of the entity that created the file.
+        /// </summary>
         public string CreatedBy => ExceptionInfo.ReturnString(_handle, FileMetaData_Created_By);
 
+        /// <summary>
+        /// Get the key-value metadata.
+        /// </summary>
+        /// <returns>An <see cref="IReadOnlyDictionary{TKey,TValue}"/> containing the key-value metadata.</returns>
         public IReadOnlyDictionary<string, string> KeyValueMetadata
         {
             get
@@ -34,13 +44,38 @@ public IReadOnlyDictionary<string, string> KeyValueMetadata
             }
         }
 
+        /// <summary>
+        /// Get the number of columns in the file.
+        /// </summary>
         public int NumColumns => ExceptionInfo.Return<int>(_handle, FileMetaData_Num_Columns);
+        /// <summary>
+        /// Get the number of rows in the file.
+        /// </summary>
         public long NumRows => ExceptionInfo.Return<long>(_handle, FileMetaData_Num_Rows);
+        /// <summary>
+        /// Get the number of row groups in the file.
+        /// </summary>
         public int NumRowGroups => ExceptionInfo.Return<int>(_handle, FileMetaData_Num_Row_Groups);
+        /// <summary>
+        /// Get the number of schema elements in the file.
+        /// </summary>
         public int NumSchemaElements => ExceptionInfo.Return<int>(_handle, FileMetaData_Num_Schema_Elements);
+        /// <summary>
+        /// Get the schema descriptor for the file.
+        /// </summary>
+        /// <returns>A <see cref="SchemaDescriptor"/> object that describes the schema of the file.</returns>
         public SchemaDescriptor Schema => _schema ??= new SchemaDescriptor(ExceptionInfo.Return<IntPtr>(_handle, FileMetaData_Schema));
+        /// <summary>
+        /// Get the total size of the file in bytes.
+        /// </summary>
         public int Size => ExceptionInfo.Return<int>(_handle, FileMetaData_Size);
+        /// <summary>
+        /// Get the Parquet format version of the file.
+        /// </summary>
         public ParquetVersion Version => ExceptionInfo.Return<ParquetVersion>(_handle, FileMetaData_Version);
+        /// <summary>
+        /// Get the version of the writer that created the file.
+        /// </summary>
         public ApplicationVersion WriterVersion => new ApplicationVersion(ExceptionInfo.Return<AppVer>(_handle, FileMetaData_Writer_Version));
 
         public bool Equals(FileMetaData? other)

csharp/LogicalColumnWriter.cs

@@ -65,6 +65,12 @@ internal static LogicalColumnWriter<TElementType> Create<TElementType>(ColumnWri
             }
         }
 
+        /// <summary>
+        /// Apply a visitor to this logical column writer.
+        /// </summary>
+        /// <typeparam name="TReturn">The return type of the visitor.</typeparam>
+        /// <param name="visitor">The visitor instance.</param>
+        /// <returns>The result of the visitor.</returns>
         public abstract TReturn Apply<TReturn>(ILogicalColumnWriterVisitor<TReturn> visitor);
 
         private sealed class Creator : IColumnDescriptorVisitor<LogicalColumnWriter>
@@ -85,6 +91,7 @@ public LogicalColumnWriter OnColumnDescriptor<TPhysical, TLogical, TElement>() w
         }
     }
 
+    /// <inheritdoc />
     public sealed class LogicalColumnWriter<TElement> : LogicalColumnWriter
     {
         private LogicalColumnWriter(ColumnWriter columnWriter, int bufferLength, ByteBuffer? byteBuffer, ILogicalBatchWriter<TElement> batchWriter)
@@ -130,21 +137,36 @@ public override void Dispose()
             base.Dispose();
         }
 
+        /// <inheritdoc />
         public override TReturn Apply<TReturn>(ILogicalColumnWriterVisitor<TReturn> visitor)
         {
             return visitor.OnLogicalColumnWriter(this);
         }
 
+        /// <summary>
+        /// Write an array of values to the column.
+        /// </summary>
+        /// <param name="values">An array of values to write.</param>
         public void WriteBatch(TElement[] values)
         {
             WriteBatch(values.AsSpan());
         }
 
+        /// <summary>
+        /// Write a range of values to the column.
+        /// </summary>
+        /// <param name="values">An array of values to write.</param>
+        /// <param name="start">The index of the first value to write.</param>
+        /// <param name="length">The number of values to write.</param>
         public void WriteBatch(TElement[] values, int start, int length)
         {
             WriteBatch(values.AsSpan(start, length));
         }
 
+        /// <summary>
+        /// Write a span of values to the column.
+        /// </summary>
+        /// <param name="values">A <see cref="ReadOnlySpan{TElement}"/> of values to write.</param>
         public void WriteBatch(ReadOnlySpan<TElement> values)
         {
             _batchWriter.WriteBatch(values);