MINOR: [FlightRPC][C++][Python][Docs] Minor tweaks to docstrings (apa…

…che#36900)

### Rationale for this change

Improves language surrounding Flight Shutdown/Wait/Serve.

### What changes are included in this PR?

Just docstring tweaks.

### Are these changes tested?

No tests, just docstrings.

### Are there any user-facing changes?

n/a

Authored-by: Bryce Mecum <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>

cpp/src/arrow/flight/server.h

@@ -202,8 +202,10 @@ class ARROW_FLIGHT_EXPORT FlightServerBase {
   Status SetShutdownOnSignals(const std::vector<int> sigs);
 
   /// \brief Start serving.
-  /// This method blocks until either Shutdown() is called or one of the signals
-  /// registered in SetShutdownOnSignals() is received.
+  /// This method blocks until the server shuts down.
+  ///
+  /// The server will start to shut down when either Shutdown() is called
+  /// or one of the signals registered in SetShutdownOnSignals() is received.
   Status Serve();
 
   /// \brief Query whether Serve() was interrupted by a signal.
@@ -212,14 +214,18 @@ class ARROW_FLIGHT_EXPORT FlightServerBase {
   /// \return int the signal number that interrupted Serve(), if any, otherwise 0
   int GotSignal() const;
 
-  /// \brief Shut down the server. Can be called from signal handler or another
-  /// thread while Serve() blocks. Optionally a deadline can be set. Once the
-  /// the deadline expires server will wait until remaining running calls
-  /// complete.
+  /// \brief Shut down the server, blocking until current requests finish.
+  ///
+  /// Can be called from a signal handler or another thread while Serve()
+  /// blocks. Optionally a deadline can be set. Once the the deadline expires
+  /// server will wait until remaining running calls complete.
   ///
+  /// Should only be called once.
   Status Shutdown(const std::chrono::system_clock::time_point* deadline = NULLPTR);
 
-  /// \brief Block until server is terminated with Shutdown.
+  /// \brief Block until server shuts down with Shutdown.
+  ///
+  /// Does not respond to signals like Serve().
   Status Wait();
 
   // Implement these methods to create your own server. The default

python/pyarrow/_flight.pyx

@@ -3016,7 +3016,7 @@ cdef class FlightServerBase(_Weakrefable):
     def serve(self):
         """Block until the server shuts down.
 
-        This method only returns if shutdown() is called or a signal a
+        This method only returns if shutdown() is called or a signal is
         received.
         """
         if self.server.get() == nullptr:
@@ -3041,6 +3041,8 @@ cdef class FlightServerBase(_Weakrefable):
         method, as then the server will block forever waiting for that
         request to finish. Instead, call this method from a background
         thread.
+
+        This method should only be called once.
         """
         # Must not hold the GIL: shutdown waits for pending RPCs to
         # complete. Holding the GIL means Python-implemented Flight