From e89b04337c3ef38e79a5ecf6b158718c1cb544c0 Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Tue, 20 Dec 2022 18:52:25 -0500
Subject: [PATCH] minor: Improve arrow-flight docs (#3372)

* minor: Improve arrow-flight docs

* prettier

* Update arrow-flight/src/lib.rs

Co-authored-by: Raphael Taylor-Davies <1781103+tustvold@users.noreply.github.com>

Co-authored-by: Raphael Taylor-Davies <1781103+tustvold@users.noreply.github.com>
---
 arrow-flight/README.md  | 11 ++++++++++-
 arrow-flight/src/lib.rs | 19 +++++++++++++++++++
 arrow/README.md         |  2 +-
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/arrow-flight/README.md b/arrow-flight/README.md
index 4b2940e45c92..76b990b0163f 100644
--- a/arrow-flight/README.md
+++ b/arrow-flight/README.md
@@ -32,4 +32,13 @@ arrow-flight = "29.0.0"
 
 Apache Arrow Flight is a gRPC based protocol for exchanging Arrow data between processes. See the blog post [Introducing Apache Arrow Flight: A Framework for Fast Data Transport](https://arrow.apache.org/blog/2019/10/13/introducing-arrow-flight/) for more information.
 
-This crate provides a Rust implementation of the [Flight.proto](../../format/Flight.proto) gRPC protocol and provides an example that demonstrates how to build a Flight server implemented with Tonic.
+This crate provides a Rust implementation of the
+[Flight.proto](../../format/Flight.proto) gRPC protocol and
+[examples](https://github.com/apache/arrow-rs/tree/master/arrow-flight/examples)
+that demonstrate how to build a Flight server implemented with [tonic](https://docs.rs/crate/tonic/latest).
+
+## Feature Flags
+
+- `flight-sql-experimental`: Enables experimental support for
+  [Apache Arrow FlightSQL](https://arrow.apache.org/docs/format/FlightSql.html),
+  a protocol for interacting with SQL databases.
diff --git a/arrow-flight/src/lib.rs b/arrow-flight/src/lib.rs
index 53ea5d4633e4..051509fb16e2 100644
--- a/arrow-flight/src/lib.rs
+++ b/arrow-flight/src/lib.rs
@@ -15,6 +15,21 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! A native Rust implementation of [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html)
+//! for exchanging [Arrow](https://arrow.apache.org) data between processes.
+//!
+//! Please see the [arrow-flight crates.io](https://crates.io/crates/arrow-flight)
+//! page for feature flags and more information.
+//!
+//! # Overview
+//!
+//! This crate contains:
+//!
+//! 1. Low level [prost] generated structs
+//!  for Flight gRPC protobuf messages, such as [`FlightData`].
+//!
+//! 2. Low level [tonic] generated [`flight_service_client`] and
+//! [`flight_service_server`].
 #![allow(rustdoc::invalid_html_tags)]
 
 use arrow_ipc::{convert, writer, writer::EncodedData, writer::IpcWriteOptions};
@@ -36,16 +51,20 @@ mod gen {
     include!("arrow.flight.protocol.rs");
 }
 
+/// Defines a `Flight` for generation or retrieval.
 pub mod flight_descriptor {
     use super::gen;
     pub use gen::flight_descriptor::DescriptorType;
 }
 
+/// Low Level [tonic] [`FlightServiceClient`](gen::flight_service_client::FlightServiceClient).
 pub mod flight_service_client {
     use super::gen;
     pub use gen::flight_service_client::FlightServiceClient;
 }
 
+/// Low Level [tonic] [`FlightServiceServer`](gen::flight_service_server::FlightServiceServer)
+/// and [`FlightService`](gen::flight_service_server::FlightService).
 pub mod flight_service_server {
     use super::gen;
     pub use gen::flight_service_server::FlightService;
diff --git a/arrow/README.md b/arrow/README.md
index 5bcdf0cafce9..4d2f8e303b8d 100644
--- a/arrow/README.md
+++ b/arrow/README.md
@@ -44,7 +44,7 @@ The `arrow` crate provides the following features which may be enabled in your `
 - `csv` (default) - support for reading and writing Arrow arrays to/from csv files
 - `json` (default) - support for reading and writing Arrow array to/from json files
 - `ipc` (default) - support for reading [Arrow IPC Format](https://arrow.apache.org/docs/format/Columnar.html#serialization-and-interprocess-communication-ipc), also used as the wire protocol in [arrow-flight](https://crates.io/crates/arrow-flight)
-- `ipc_compression`  - Enables reading and writing compressed IPC streams (also enables `ipc`)
+- `ipc_compression` - Enables reading and writing compressed IPC streams (also enables `ipc`)
 - `prettyprint` - support for formatting record batches as textual columns
 - `js` - support for building arrow for WebAssembly / JavaScript
 - `simd` - (_Requires Nightly Rust_) Use alternate hand optimized