Merge pull request #62 from atolab/undeclaration_on_drop

docs: add undeclaration on drop documentation for Rust

content/docs/migration_1.0/Rust.md

@@ -109,6 +109,37 @@ session.close().await.unwrap();
 subscriber_task.await.unwrap()
 ```
 
+## Callbacks run in background until session is closed
+
+Session entities, e.g. subscribers, declared with callbacks are no longer undeclared when they are dropped; there is no longer need to keep a reference to an entity when the intent is to have it run until the session is closed.
+
+```rust
+let session = zenoh::open(zenoh::config::default()).await.unwrap();
+session
+    .declare_subscriber("key/ expression")
+    .callback(|sample| { println!("Received: {} {:?}", sample. key_expr(), sample. payload()) })
+    .await
+    .unwrap();
+// subscriber run in background until the session is closed
+// no need to keep a variable around
+```
+
+If you still want the entity to be undeclared when dropped, you can simply use `with` instead of `callback`; it may just require you to annotate the callback, as type inference is not as good as with `callback` method.
+
+```rust
+let session = zenoh::open(zenoh::config::default()).await.unwrap();
+let subscriber = session
+    .declare_subscriber("key/ expression")
+    // annotation needed
+    .with(|sample: Sample| { println!("Received: {} {:?}", sample. key_expr(), sample. payload()) })
+    .await
+    .unwrap();
+// subscriber is undeclared when dropped
+```
+
+*Going into details, a new method `undeclare_on_drop(bool)` – default to `true`, has been added to the builders, and `callback(cb)` is now simply a shortcut to `with(cb).undeclare_on_drop(false)`. 
+However, the normal user would rarely need to call this method directly.*
+
 ## Value is gone, long live ZBytes
 
 We have replaced `Value` with `ZBytes` and `Encoding` , and added a number of conversion implementations such that user structs can be serialized into `ZBytes`, sent via Zenoh, and de-serialized from `ZBytes` with ease.