Add middleware to Flight docs

cpp/src/arrow/flight/middleware.h

@@ -68,14 +68,21 @@ struct ARROW_FLIGHT_EXPORT HeaderIterator {
 /// \brief A read-only wrapper around headers for an RPC call.
 class ARROW_FLIGHT_EXPORT CallHeaders {
  public:
+  /// \brief The iterator type. Dereferences to a std::pair of string
+  /// views.
   typedef HeaderIterator const_iterator;
 
   virtual ~CallHeaders() = default;
 
+  /// \brief Get all the values for the given header.
   virtual std::pair<const_iterator, const_iterator> GetHeaders(
       const std::string& key) const = 0;
+  /// \brief Count the number of values for the header (returns 0 if
+  /// header does not exist).
   virtual std::size_t Count(const std::string& key) const = 0;
+  /// \brief Const iterator for header-value pairs.
   virtual const_iterator cbegin() const noexcept = 0;
+  /// \brief Const iterator for header-value pairs.
   virtual const_iterator cend() const noexcept = 0;
 };
 
@@ -84,6 +91,7 @@ class ARROW_FLIGHT_EXPORT AddCallHeaders {
  public:
   virtual ~AddCallHeaders() = default;
 
+  /// \brief Add a header to be sent to the client.
   virtual void AddHeader(const std::string& key, const std::string& value) = 0;
 };
 
@@ -103,6 +111,7 @@ enum class FlightMethod : char {
 /// \brief Information about an instance of a Flight RPC.
 class ARROW_FLIGHT_EXPORT CallInfo {
  public:
+  /// \brief The RPC method of this call.
   FlightMethod method;
 };
 

docs/source/cpp/api/flight.rst

@@ -39,6 +39,18 @@ Common Types
    :project: arrow_cpp
    :members:
 
+.. doxygenclass:: arrow::flight::AddCallHeaders
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::flight::CallInfo
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::flight::CallHeaders
+   :project: arrow_cpp
+   :members:
+
 .. doxygenstruct:: arrow::flight::Criteria
    :project: arrow_cpp
    :members:
@@ -63,6 +75,9 @@ Common Types
    :project: arrow_cpp
    :members:
 
+.. doxygenenum:: arrow::flight::FlightMethod
+   :project: arrow_cpp
+
 .. doxygenstruct:: arrow::flight::Location
    :project: arrow_cpp
    :members:
@@ -102,6 +117,14 @@ Clients
    :project: arrow_cpp
    :members:
 
+.. doxygenclass:: arrow::flight::ClientMiddleware
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::flight::ClientMiddlewareFactory
+   :project: arrow_cpp
+   :members:
+
 .. doxygentypedef:: arrow::flight::TimeoutDuration
    :project: arrow_cpp
 
@@ -152,6 +175,14 @@ Servers
    :project: arrow_cpp
    :members:
 
+.. doxygenclass:: arrow::flight::ServerMiddleware
+   :project: arrow_cpp
+   :members:
+
+.. doxygenclass:: arrow::flight::ServerMiddlewareFactory
+   :project: arrow_cpp
+   :members:
+
 .. doxygenclass:: arrow::flight::SimpleFlightListing
    :project: arrow_cpp
    :members:

docs/source/python/api/flight.rst

@@ -61,6 +61,8 @@ Flight Client
 
     FlightCallOptions
     FlightClient
+    ClientMiddlewareFactory
+    ClientMiddleware
 
 Flight Server
 -------------
@@ -71,6 +73,8 @@ Flight Server
     FlightServerBase
     GeneratorStream
     RecordBatchStream
+    ServerMiddlewareFactory
+    ServerMiddleware
 
 Authentication
 --------------
@@ -80,3 +84,12 @@ Authentication
 
     ClientAuthHandler
     ServerAuthHandler
+
+Middleware
+----------
+
+.. autosummary::
+   :toctree: ../generated/
+
+    FlightMethod
+    CallInfo

python/pyarrow/_flight.pyx

@@ -1845,7 +1845,7 @@ cdef class ClientMiddlewareFactory:
 
         Returns
         -------
-        instance : ClientMiddleware optional
+        instance : ClientMiddleware
             An instance of ClientMiddleware (the instance to use for
             the call), or None if this call is not intercepted.
 
@@ -1865,7 +1865,7 @@ cdef class ClientMiddleware:
 
         Returns
         -------
-        headers : dict optional
+        headers : dict
             A dictionary of header values to add to the response, or
             None if no headers are to be added. The dictionary should
             have string keys and string or list-of-string values.
@@ -1929,13 +1929,13 @@ cdef class ServerMiddlewareFactory:
 
         Returns
         -------
-        instance : ServerMiddleware optional
+        instance : ServerMiddleware
             An instance of ServerMiddleware (the instance to use for
             the call), or None if this call is not intercepted.
 
         Raises
         ------
-        ArrowException
+        exception : pyarrow.ArrowException
             If an exception is raised, the call will be rejected with
             the given error.
 
@@ -1955,7 +1955,7 @@ cdef class ServerMiddleware:
 
         Returns
         -------
-        headers : dict optional
+        headers : dict
             A dictionary of header values to add to the response, or
             None if no headers are to be added. The dictionary should
             have string keys and string or list-of-string values.
@@ -1967,7 +1967,7 @@ cdef class ServerMiddleware:
 
         Parameters
         ----------
-        exception : ArrowException
+        exception : pyarrow.ArrowException
             If the call errored, this is the equivalent
             exception. Will be None if the call succeeded.
 
@@ -2075,7 +2075,7 @@ cdef class FlightServerBase:
     tls_certificates : list optional, default None
         A list of (certificate, key) pairs.
     middleware : list optional, default None
-        A dictionary of (middleware key, middleware factory) items.
+        A dictionary of :class:`ServerMiddlewareFactory` items.
     """
 
     cdef: