add more docs

Signed-off-by: Bugen Zhao <i@bugenzhao.com>

Author: BugenZhao

madsim-tonic/src/transport/channel.rs

@@ -77,6 +77,8 @@ impl Endpoint {
     }
 
     /// Sets the tower service default internal buffer size.
+    ///
+    /// Note: this setting is currently ignored by the madsim transport implementation.
     pub fn buffer_size(self, sz: impl Into<Option<usize>>) -> Self {
         // ignore this setting
         let _ = sz.into();
@@ -105,6 +107,8 @@ impl Endpoint {
     }
 
     /// Create a channel that connects lazily.
+    ///
+    /// Note: madsim transport is not backed by a real HTTP/2 connection pool.
     pub fn connect_lazy(&self) -> Channel {
         Channel {
             ep: MultiEndpoint::new_one(self.clone()),
@@ -114,7 +118,7 @@ impl Endpoint {
 
     /// Create a channel that connects lazily using a custom connector.
     ///
-    /// The connector is ignored in simulation mode.
+    /// Note: the connector is currently ignored by the madsim transport implementation.
     pub fn connect_with_connector_lazy<C>(&self, _connector: C) -> Channel {
         self.connect_lazy()
     }
@@ -155,6 +159,8 @@ impl Endpoint {
     }
 
     /// Configures TLS for the endpoint.
+    ///
+    /// Note: TLS is currently ignored by the madsim transport implementation.
     #[cfg(any(
         feature = "tls-native-roots",
         feature = "tls-webpki-roots",
@@ -228,6 +234,8 @@ impl Endpoint {
     }
 
     /// Sets the max size of received header frames.
+    ///
+    /// Note: this setting is currently ignored by the madsim transport implementation.
     pub fn http2_max_header_list_size(self, size: u32) -> Self {
         // ignore this setting
         let _ = size;
@@ -236,7 +244,7 @@ impl Endpoint {
 
     /// Sets the executor used to spawn async tasks.
     ///
-    /// The executor is ignored in simulation mode.
+    /// Note: the executor is currently ignored by the madsim transport implementation.
     pub fn executor<E>(self, _executor: E) -> Self
     where
         E: Clone + Send + Sync + 'static,
@@ -246,7 +254,7 @@ impl Endpoint {
 
     /// Sets the local address used when connecting.
     ///
-    /// The address is ignored in simulation mode.
+    /// Note: the address is currently ignored by the madsim transport implementation.
     pub fn local_address(self, addr: Option<std::net::IpAddr>) -> Self {
         // ignore this setting
         let _ = addr;
@@ -258,15 +266,22 @@ impl Endpoint {
         &self.uri
     }
 
+    /// Returns whether `TCP_NODELAY` is enabled.
+    ///
+    /// Note: this always returns `true` for API compatibility.
     pub fn get_tcp_nodelay(&self) -> bool {
         // We don't store this option; tonic defaults to true.
         true
     }
 
+    /// Returns the configured connect timeout.
     pub fn get_connect_timeout(&self) -> Option<Duration> {
         self.connect_timeout
     }
 
+    /// Returns the configured TCP keepalive setting.
+    ///
+    /// Note: this always returns `None` for API compatibility.
     pub fn get_tcp_keepalive(&self) -> Option<Duration> {
         None
     }

madsim-tonic/src/transport/server.rs

@@ -68,7 +68,8 @@ impl<L> Server<L> {
 
     /// Create a router with the optional `S` typed service as the first service.
     ///
-    /// When `None`, this returns an empty router (requests will return Unimplemented).
+    /// When `None`, this returns an empty router (requests will return
+    /// [`Code::Unimplemented`]).
     pub fn add_optional_service<S>(&mut self, svc: Option<S>) -> Router<L>
     where
         S: Service<
@@ -182,13 +183,17 @@ impl<L> Server<L> {
     }
 
     /// Sets the maximum time a connection may exist.
+    ///
+    /// Note: this setting is currently ignored by the madsim transport implementation.
     #[must_use]
     pub fn max_connection_age(self, _max_connection_age: Duration) -> Self {
         // ignore this setting
         self
     }
 
     /// Sets the max size of received header frames.
+    ///
+    /// Note: this setting is currently ignored by the madsim transport implementation.
     #[must_use]
     pub fn http2_max_header_list_size(self, _max: impl Into<Option<u32>>) -> Self {
         // ignore this setting
@@ -224,6 +229,8 @@ impl<L> Server<L> {
     }
 
     /// Intercept inbound headers and add a tracing span to each response future.
+    ///
+    /// Note: this setting is currently ignored by the madsim transport implementation.
     #[must_use]
     pub fn trace_fn<FN>(self, _f: FN) -> Self
     where
@@ -273,6 +280,8 @@ impl<L> Router<L> {
     }
 
     /// Add an optional service to this router.
+    ///
+    /// When `None`, this leaves the router unchanged.
     pub fn add_optional_service<S>(self, svc: Option<S>) -> Self
     where
         S: Service<