modify comment and doc

Author: wgtmac

cpp/src/parquet/properties.h

@@ -524,9 +524,11 @@ class PARQUET_EXPORT WriterProperties {
 
     /// Enable writing page index in general for all columns. Default disabled.
     ///
-    /// Page index contains statistics for data pages and can be used to skip pages
-    /// when scanning data in ordered and unordered columns. Note that it does not
-    /// write statistics to the page header once page index is enabled.
+    /// Writing statistics to the page index disables the old method of writing
+    /// statistics to each data page header.
+    /// The page index makes filtering more efficient than the page header, as
+    /// it gathers all the statistics for a Parquet file in a single place,
+    /// avoiding scattered I/O.
     ///
     /// Please check the link below for more details:
     /// https://github.com/apache/parquet-format/blob/master/PageIndex.md

docs/source/cpp/parquet.rst

@@ -575,14 +575,17 @@ Miscellaneous
 +--------------------------+----------+----------+---------+
 | Feature                  | Reading  | Writing  | Notes   |
 +==========================+==========+==========+=========+
-| Column Index             | ✓        | ✓        |         |
+| Column Index             | ✓        | ✓        | \(1)    |
 +--------------------------+----------+----------+---------+
-| Offset Index             | ✓        | ✓        |         |
+| Offset Index             | ✓        | ✓        | \(1)    |
 +--------------------------+----------+----------+---------+
-| Bloom Filter             | ✓        | ✓        | \(1)    |
+| Bloom Filter             | ✓        | ✓        | \(2)    |
 +--------------------------+----------+----------+---------+
 | CRC checksums            | ✓        | ✓        |         |
 +--------------------------+----------+----------+---------+
 
-* \(1) APIs are provided for creating, serializing and deserializing Bloom
+* \(1) Access to the Column and Offset Index structures is provided, but
+  data read APIs do not currently make any use of them.
+
+* \(2) APIs are provided for creating, serializing and deserializing Bloom
   Filters, but they are not integrated into data read APIs.