Add FlightSQL module docs and links to arrow-flight crates (#4012)

* Add FlightSQL module docs and links to `arrow-flight` crates

* Updates

* Update arrow-flight/src/sql/mod.rs

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

* Copy editing and improve links

---------

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

arrow-flight/src/lib.rs

@@ -30,6 +30,11 @@
 //!
 //! 2. Low level [tonic] generated [`flight_service_client`] and
 //! [`flight_service_server`].
+//!
+//! 3. Experimental support for [Flight SQL] in [`sql`]. Requires the
+//! `flight-sql-experimental` feature of this crate to be activated.
+//!
+//! [Flight SQL]: https://arrow.apache.org/docs/format/FlightSql.html
 #![allow(rustdoc::invalid_html_tags)]
 
 use arrow_ipc::{convert, writer, writer::EncodedData, writer::IpcWriteOptions};

arrow-flight/src/sql/client.rs

@@ -15,6 +15,8 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! A FlightSQL Client [`FlightSqlServiceClient`]
+
 use base64::prelude::BASE64_STANDARD;
 use base64::Engine;
 use bytes::Bytes;

arrow-flight/src/sql/mod.rs

@@ -15,6 +15,27 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Support for execute SQL queries using [Apache Arrow] [Flight SQL].
+//!
+//! [Flight SQL] is built on top of Arrow Flight RPC framework, by
+//! defining specific messages, encoded using the protobuf format,
+//! sent in the[`FlightDescriptor::cmd`] field to [`FlightService`]
+//! endpoints such as[`get_flight_info`] and [`do_get`].
+//!
+//! This module contains:
+//! 1. [prost] generated structs for FlightSQL messages such as [`CommandStatementQuery`]
+//! 2. Helpers for encoding and decoding FlightSQL messages: [`Any`] and [`Command`]
+//! 3. A [`FlightSqlServiceClient`] for interacting with FlightSQL servers.
+//! 4. A [`FlightSqlService`] to help building FlightSQL servers from [`FlightService`].
+//!
+//! [Flight SQL]: https://arrow.apache.org/docs/format/FlightSql.html
+//! [Apache Arrow]: https://arrow.apache.org
+//! [`FlightDescriptor::cmd`]: crate::FlightDescriptor::cmd
+//! [`FlightService`]: crate::flight_service_server::FlightService
+//! [`get_flight_info`]: crate::flight_service_server::FlightService::get_flight_info
+//! [`do_get`]: crate::flight_service_server::FlightService::do_get
+//! [`FlightSqlServiceClient`]: client::FlightSqlServiceClient
+//! [`FlightSqlService`]: server::FlightSqlService
 use arrow_schema::ArrowError;
 use bytes::Bytes;
 use paste::paste;
@@ -90,8 +111,8 @@ macro_rules! prost_message_ext {
             )*
 
                 as_item! {
-                /// Helper to convert to/from protobuf [`Any`]
-                /// to a strongly typed enum.
+                /// Helper to convert to/from protobuf [`Any`] message
+                /// to a specific FlightSQL command message.
                 ///
                 /// # Example
                 /// ```rust

arrow-flight/src/sql/server.rs

@@ -15,6 +15,8 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Helper trait [`FlightSqlService`] for implementing a [`FlightService`] that implements FlightSQL.
+
 use std::pin::Pin;
 
 use crate::sql::{Any, Command};