docs(contract): improve EventStream docs (#1450)

ethers-contract/src/event.rs

@@ -115,7 +115,44 @@ where
     M: Middleware,
     D: EthLogDecode,
 {
-    /// Returns a stream for the event
+    /// Turns this event filter into `Stream` that yields decoded events.
+    ///
+    /// This will first install a new logs filter via [`eth_newFilter`](https://docs.alchemy.com/alchemy/apis/ethereum/eth-newfilter) using the configured `filter` object. See also [`FilterWatcher`](ethers_providers::FilterWatcher).
+    ///
+    /// Once the filter is created, this will periodically call [`eth_getFilterChanges`](https://docs.alchemy.com/alchemy/apis/ethereum/eth-getfilterchanges) to get the newest logs and decode them
+    ///
+    /// **Note:** Compared to [`Self::subscribe`], which is only available on `PubsubClient`s, such
+    /// as Websocket, this is a poll-based subscription, as the node does not notify us when a new
+    /// matching log is available, instead we have to actively ask for new logs using additional RPC
+    /// requests, and this is done on an interval basis.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # async fn test<M:ethers_providers::Middleware>(contract: ethers_contract::Contract<M>) {
+    /// # use ethers_core::types::*;
+    /// # use futures_util::stream::StreamExt;
+    /// # use ethers_contract::{Contract, EthEvent};
+    ///
+    /// // The event we want to get
+    /// #[derive(Clone, Debug, EthEvent)]
+    /// pub struct Approval {
+    ///     #[ethevent(indexed)]
+    ///     pub token_owner: Address,
+    ///     #[ethevent(indexed)]
+    ///     pub spender: Address,
+    ///     pub tokens: U256,
+    /// }
+    ///
+    /// let ev = contract.event::<Approval>().from_block(1337).to_block(2000);
+    /// let mut event_stream = ev.stream().await.unwrap();
+    ///
+    ///  while let Some(Ok(approval)) = event_stream.next().await {
+    ///      let Approval{token_owner,spender,tokens} = approval;
+    /// }
+    ///
+    /// # }
+    /// ```
     pub async fn stream(
         &'a self,
     ) -> Result<
@@ -136,6 +173,8 @@ where
     D: EthLogDecode,
 {
     /// Returns a subscription for the event
+    ///
+    /// See also [Self::stream()].
     pub async fn subscribe(
         &'a self,
     ) -> Result<