docs: Mark native_comet scan as deprecated (#3274)

Author: andygrove

common/src/main/scala/org/apache/comet/CometConf.scala

@@ -113,8 +113,9 @@ object CometConf extends ShimCometConf {
 
   // Deprecated: native_comet uses mutable buffers incompatible with Arrow FFI best practices
   // and does not support complex types. Use native_iceberg_compat or auto instead.
+  // This will be removed in a future release.
   // See: https://github.com/apache/datafusion-comet/issues/2186
-  @deprecated("Use SCAN_AUTO instead", "0.9.0")
+  @deprecated("Use SCAN_AUTO instead. native_comet will be removed in a future release.", "0.9.0")
   val SCAN_NATIVE_COMET = "native_comet"
   val SCAN_NATIVE_DATAFUSION = "native_datafusion"
   val SCAN_NATIVE_ICEBERG_COMPAT = "native_iceberg_compat"
@@ -125,9 +126,9 @@ object CometConf extends ShimCometConf {
     .doc(
       s"The implementation of Comet Native Scan to use. Available modes are `$SCAN_NATIVE_COMET`," +
         s"`$SCAN_NATIVE_DATAFUSION`, and `$SCAN_NATIVE_ICEBERG_COMPAT`. " +
-        s"`$SCAN_NATIVE_COMET` (DEPRECATED) is for the original Comet native scan which " +
-        "uses a jvm based parquet file reader and native column decoding. " +
-        "Supports simple types only. " +
+        s"`$SCAN_NATIVE_COMET` (DEPRECATED - will be removed in a future release) is for the " +
+        "original Comet native scan which uses a jvm based parquet file reader and native " +
+        "column decoding. Supports simple types only. " +
         s"`$SCAN_NATIVE_DATAFUSION` is a fully native implementation of scan based on " +
         "DataFusion. " +
         s"`$SCAN_NATIVE_ICEBERG_COMPAT` is the recommended native implementation that " +

docs/source/contributor-guide/ffi.md

@@ -177,8 +177,9 @@ message Scan {
 
 #### When ownership is NOT transferred to native:
 
-If the data originates from `native_comet` scan (or from `native_iceberg_compat` in some cases), then ownership is
-not transferred to native and the JVM may re-use the underlying buffers in the future.
+If the data originates from `native_comet` scan (deprecated, will be removed in a future release) or from
+`native_iceberg_compat` in some cases, then ownership is not transferred to native and the JVM may re-use the
+underlying buffers in the future.
 
 It is critical that the native code performs a deep copy of the arrays if the arrays are to be buffered by
 operators such as `SortExec` or `ShuffleWriterExec`, otherwise data corruption is likely to occur.

docs/source/contributor-guide/parquet_scans.md

@@ -26,11 +26,11 @@ settings. Most users should not need to change this setting. However, it is poss
 a particular implementation for all scan operations by setting this configuration property to one of the following
 implementations.
 
-| Implementation          | Description                                                                                                                                                                          |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `native_comet`          | This implementation provides strong compatibility with Spark but does not support complex types. This is the original scan implementation in Comet and may eventually be removed.    |
-| `native_iceberg_compat` | This implementation delegates to DataFusion's `DataSourceExec` but uses a hybrid approach of JVM and native code. This scan is designed to be integrated with Iceberg in the future. |
-| `native_datafusion`     | This experimental implementation delegates to DataFusion's `DataSourceExec` for full native execution. There are known compatibility issues when using this scan.                    |
+| Implementation          | Description                                                                                                                                                                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `native_comet`          | **Deprecated.** This implementation provides strong compatibility with Spark but does not support complex types. This is the original scan implementation in Comet and will be removed in a future release. |
+| `native_iceberg_compat` | This implementation delegates to DataFusion's `DataSourceExec` but uses a hybrid approach of JVM and native code. This scan is designed to be integrated with Iceberg in the future.                        |
+| `native_datafusion`     | This experimental implementation delegates to DataFusion's `DataSourceExec` for full native execution. There are known compatibility issues when using this scan.                                           |
 
 The `native_datafusion` and `native_iceberg_compat` scans provide the following benefits over the `native_comet`
 implementation:
@@ -71,7 +71,9 @@ The `native_datafusion` scan has some additional limitations:
 
 There are some differences in S3 support between the scan implementations.
 
-### `native_comet`
+### `native_comet` (Deprecated)
+
+> **Note:** The `native_comet` scan implementation is deprecated and will be removed in a future release.
 
 The `native_comet` Parquet scan implementation reads data from S3 using the [Hadoop-AWS module](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html), which
 is identical to the approach commonly used with vanilla Spark. AWS credential configuration and other Hadoop S3A

docs/source/contributor-guide/roadmap.md

@@ -42,8 +42,8 @@ more Spark SQL tests and fully implementing ANSI support ([#313]) for all suppor
 
 ### Removing the native_comet scan implementation
 
-We are working towards deprecating ([#2186]) and removing ([#2177]) the `native_comet` scan implementation, which
-is the original scan implementation that uses mutable buffers (which is incompatible with best practices around
+The `native_comet` scan implementation is now deprecated and will be removed in a future release ([#2186], [#2177]).
+This is the original scan implementation that uses mutable buffers (which is incompatible with best practices around
 Arrow FFI) and does not support complex types.
 
 Now that the default `auto` scan mode uses `native_iceberg_compat` (which is based on DataFusion's `DataSourceExec`),