From df0d45be486fe9f966bb8fad8ec71c7648bee92e Mon Sep 17 00:00:00 2001
From: andrey <agrey0175@proton.me>
Date: Tue, 27 Feb 2024 10:15:38 +0800
Subject: [PATCH 1/6] added better documentation and code snipppets for the
 use_resource, use_future, use_effect and use_context hooks

---
 packages/hooks/src/use_context.rs   | 27 +++++++++++++++++++++++++++
 packages/hooks/src/use_coroutine.rs |  3 ++-
 packages/hooks/src/use_effect.rs    | 18 +++++++++++++++---
 packages/hooks/src/use_future.rs    | 24 ++++++++++++++++++++++++
 packages/hooks/src/use_resource.rs  | 26 +++++++++++++++++++++++++-
 packages/signals/src/impls.rs       |  1 +
 packages/signals/src/signal.rs      |  4 ++--
 packages/signals/tests/create.rs    |  3 +++
 8 files changed, 99 insertions(+), 7 deletions(-)

diff --git a/packages/hooks/src/use_context.rs b/packages/hooks/src/use_context.rs
index ac3bb62ea..5deafd417 100644
--- a/packages/hooks/src/use_context.rs
+++ b/packages/hooks/src/use_context.rs
@@ -14,6 +14,18 @@ pub fn try_use_context<T: 'static + Clone>() -> Option<T> {
 /// Consume some context in the tree, providing a sharable handle to the value
 ///
 /// Does not regenerate the value if the value is changed at the parent.
+/// ```rust
+/// fn Parent() -> Element {
+///     use_context_provider(|| Theme::Dark);
+///     rsx! { Child {} }
+/// }
+/// #[component]
+/// fn Child() -> Element {
+///     //gets context provided by parent element with use_context_provider
+///     let user_theme = use_context::<Theme>();
+///     rsx! { "user using dark mode: {user_theme == Theme::Dark}" }
+/// }
+/// ```
 #[must_use]
 pub fn use_context<T: 'static + Clone>() -> T {
     use_hook(|| consume_context::<T>())
@@ -22,6 +34,21 @@ pub fn use_context<T: 'static + Clone>() -> T {
 /// Provide some context via the tree and return a reference to it
 ///
 /// Once the context has been provided, it is immutable. Mutations should be done via interior mutability.
+/// Context can be read by any child components of the context provider, and is a solution to prop
+/// drilling, using a context provider with a Signal inside is a good way to provide global/shared
+/// state in your app:
+/// ```rust
+///fn app() -> Element {
+///    use_context_provider(|| Signal::new(0));
+///    rsx! { Child {} }
+///}
+// This component does read from the signal, so when the signal changes it will rerun
+///#[component]
+///fn Child() -> Element {
+///    let signal: Signal<i32> = use_context();
+///    rsx! { "{signal}" }
+///}
+/// ```
 pub fn use_context_provider<T: 'static + Clone>(f: impl FnOnce() -> T) -> T {
     use_hook(|| {
         let val = f();
diff --git a/packages/hooks/src/use_coroutine.rs b/packages/hooks/src/use_coroutine.rs
index 06f342ceb..4834c5431 100644
--- a/packages/hooks/src/use_coroutine.rs
+++ b/packages/hooks/src/use_coroutine.rs
@@ -93,7 +93,8 @@ where
 }
 
 /// Get a handle to a coroutine higher in the tree
-///
+/// Analagous to use_context_provider and use_context,
+/// but used for coroutines specifically
 /// See the docs for [`use_coroutine`] for more details.
 #[must_use]
 pub fn use_coroutine_handle<M: 'static>() -> Coroutine<M> {
diff --git a/packages/hooks/src/use_effect.rs b/packages/hooks/src/use_effect.rs
index a3d16f420..97a603b21 100644
--- a/packages/hooks/src/use_effect.rs
+++ b/packages/hooks/src/use_effect.rs
@@ -1,10 +1,22 @@
 use dioxus_core::prelude::*;
 use dioxus_signals::ReactiveContext;
 
-/// Create a new effect. The effect will be run immediately and whenever any signal it reads changes.
-/// The signal will be owned by the current component and will be dropped when the component is dropped.
-///
+/// use_effect will subscribe to any changes in the signal values it captures
+/// effects will always run after first mount and then whenever the signal values change
 /// If the use_effect call was skipped due to an early return, the effect will no longer activate.
+/// ```rust
+/// fn app() -> Element {
+///     let mut count = use_signal(|| 0);
+///     //the effect runs again each time count changes
+///     use_effect(move || println!("Count changed to {count}"));
+///
+///     rsx! {
+///         h1 { "High-Five counter: {count}" }
+///         button { onclick: move |_| count += 1, "Up high!" }
+///         button { onclick: move |_| count -= 1, "Down low!" }
+///     }
+/// }
+/// ```
 pub fn use_effect(mut callback: impl FnMut() + 'static) {
     // let mut run_effect = use_hook(|| CopyValue::new(true));
     // use_hook_did_run(move |did_run| run_effect.set(did_run));
diff --git a/packages/hooks/src/use_future.rs b/packages/hooks/src/use_future.rs
index 4d69879aa..d2619f624 100644
--- a/packages/hooks/src/use_future.rs
+++ b/packages/hooks/src/use_future.rs
@@ -12,6 +12,30 @@ use std::future::Future;
 ///
 /// The future is spawned on the next call to `flush_sync` which means that it will not run on the server.
 /// To run a future on the server, you should use `spawn` directly.
+/// use_future assumes your future will never complete - **it won't return a value**.
+/// If you want to return a value, use `use_resource` instead.
+/// ```rust
+/// fn app() -> Element {
+///     let mut count = use_signal(|| 0);
+///     let mut running = use_signal(|| true);
+///     // use_future will spawn an infinitely running future that can be started and stopped
+///     use_future(move || async move {
+///         loop {
+///            if running() {
+///                count += 1;
+///            }
+///            tokio::time::sleep(Duration::from_millis(400)).await;
+///        }
+///     });
+///     rsx! {
+///         div {
+///             h1 { "Current count: {count}" }
+///             button { onclick: move |_| running.toggle(), "Start/Stop the count"}
+///             button { onclick: move |_| count.set(0), "Reset the count" }
+///         }
+///     }
+/// }
+/// ```
 pub fn use_future<F>(mut future: impl FnMut() -> F + 'static) -> UseFuture
 where
     F: Future + 'static,
diff --git a/packages/hooks/src/use_resource.rs b/packages/hooks/src/use_resource.rs
index 222b62e7e..389697d74 100644
--- a/packages/hooks/src/use_resource.rs
+++ b/packages/hooks/src/use_resource.rs
@@ -10,8 +10,32 @@ use futures_util::{future, pin_mut, FutureExt};
 use std::future::Future;
 
 /// A memo that resolve to a value asynchronously.
+/// Unlike `use_future`, `use_resource` runs on the **server**
+/// See [`Resource`] for more details.
+/// ```rust
+///fn app() -> Element {
+///    let country = use_signal(|| WeatherLocation {
+///        city: "Berlin".to_string(),
+///        country: "Germany".to_string(),
+///        coordinates: (52.5244, 13.4105)
+///    });
 ///
-/// This runs on the server
+///    let current_weather = //run a future inside the use_resource hook
+///        use_resource(move || async move { get_weather(&country.read().clone()).await });
+///    
+///    rsx! {
+///        //the value of the future can be polled to
+///        //conditionally render elements based off if the future
+///        //finished (Some(Ok(_)), errored Some(Err(_)),
+///        //or is still finishing (None)
+///        match current_weather.value() {
+///            Some(Ok(weather)) => WeatherElement { weather },
+///            Some(Err(e)) => p { "Loading weather failed, {e}" }
+///            None =>  p { "Loading..." }
+///        }
+///    }
+///}
+/// ```
 #[must_use = "Consider using `cx.spawn` to run a future without reading its value"]
 pub fn use_resource<T, F>(future: impl Fn() -> F + 'static) -> Resource<T>
 where
diff --git a/packages/signals/src/impls.rs b/packages/signals/src/impls.rs
index 3d120b54e..9cc790a48 100644
--- a/packages/signals/src/impls.rs
+++ b/packages/signals/src/impls.rs
@@ -5,6 +5,7 @@ use crate::write::Writable;
 use crate::{GlobalMemo, GlobalSignal, MappedSignal, ReadOnlySignal, SignalData};
 use generational_box::{AnyStorage, Storage};
 
+use std::ops::Index;
 use std::{
     fmt::{Debug, Display},
     ops::{Add, Div, Mul, Sub},
diff --git a/packages/signals/src/signal.rs b/packages/signals/src/signal.rs
index 44de51082..3d2ea96a2 100644
--- a/packages/signals/src/signal.rs
+++ b/packages/signals/src/signal.rs
@@ -10,8 +10,8 @@ use generational_box::{AnyStorage, Storage, SyncStorage, UnsyncStorage};
 use std::{
     any::Any,
     collections::HashSet,
-    ops::{Deref, DerefMut},
-    sync::Mutex,
+    ops::{Deref, DerefMut, Index, IndexMut},
+    sync::{Arc, Mutex},
 };
 
 /// Creates a new Signal. Signals are a Copy state management solution with automatic dependency tracking.
diff --git a/packages/signals/tests/create.rs b/packages/signals/tests/create.rs
index 7b17310b6..f9caddd2e 100644
--- a/packages/signals/tests/create.rs
+++ b/packages/signals/tests/create.rs
@@ -1,5 +1,8 @@
 #![allow(unused, non_upper_case_globals, non_snake_case)]
 
+use std::collections::HashMap;
+use std::sync::Arc;
+
 use dioxus::prelude::*;
 use dioxus_core::ElementId;
 use dioxus_core::NoOpMutations;

From 24ebc1e628642659c93f470d78eb3748f60c4193 Mon Sep 17 00:00:00 2001
From: andrey <agrey0175@proton.me>
Date: Tue, 27 Feb 2024 10:32:55 +0800
Subject: [PATCH 2/6] added better documentation and code snipppets for the
 use_resource, use_future, use_effect and use_context hooks

---
 packages/signals/src/impls.rs    | 1 -
 packages/signals/src/signal.rs   | 4 ++--
 packages/signals/tests/create.rs | 3 ---
 3 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/packages/signals/src/impls.rs b/packages/signals/src/impls.rs
index 9cc790a48..3d120b54e 100644
--- a/packages/signals/src/impls.rs
+++ b/packages/signals/src/impls.rs
@@ -5,7 +5,6 @@ use crate::write::Writable;
 use crate::{GlobalMemo, GlobalSignal, MappedSignal, ReadOnlySignal, SignalData};
 use generational_box::{AnyStorage, Storage};
 
-use std::ops::Index;
 use std::{
     fmt::{Debug, Display},
     ops::{Add, Div, Mul, Sub},
diff --git a/packages/signals/src/signal.rs b/packages/signals/src/signal.rs
index 3d2ea96a2..44de51082 100644
--- a/packages/signals/src/signal.rs
+++ b/packages/signals/src/signal.rs
@@ -10,8 +10,8 @@ use generational_box::{AnyStorage, Storage, SyncStorage, UnsyncStorage};
 use std::{
     any::Any,
     collections::HashSet,
-    ops::{Deref, DerefMut, Index, IndexMut},
-    sync::{Arc, Mutex},
+    ops::{Deref, DerefMut},
+    sync::Mutex,
 };
 
 /// Creates a new Signal. Signals are a Copy state management solution with automatic dependency tracking.
diff --git a/packages/signals/tests/create.rs b/packages/signals/tests/create.rs
index f9caddd2e..7b17310b6 100644
--- a/packages/signals/tests/create.rs
+++ b/packages/signals/tests/create.rs
@@ -1,8 +1,5 @@
 #![allow(unused, non_upper_case_globals, non_snake_case)]
 
-use std::collections::HashMap;
-use std::sync::Arc;
-
 use dioxus::prelude::*;
 use dioxus_core::ElementId;
 use dioxus_core::NoOpMutations;

From 5a73147d69be36368d92c79f0643124c15b2aa6a Mon Sep 17 00:00:00 2001
From: andrey <agrey0175@proton.me>
Date: Tue, 27 Feb 2024 10:36:05 +0800
Subject: [PATCH 3/6] added better documentation and code snipppets for the
 use_resource, use_future, use_effect and use_context hooks

---
 packages/hooks/src/use_context.rs | 7 +++++--
 packages/hooks/src/use_effect.rs  | 2 +-
 packages/hooks/src/use_future.rs  | 8 ++++----
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/packages/hooks/src/use_context.rs b/packages/hooks/src/use_context.rs
index 5deafd417..27c586e4f 100644
--- a/packages/hooks/src/use_context.rs
+++ b/packages/hooks/src/use_context.rs
@@ -45,8 +45,11 @@ pub fn use_context<T: 'static + Clone>() -> T {
 // This component does read from the signal, so when the signal changes it will rerun
 ///#[component]
 ///fn Child() -> Element {
-///    let signal: Signal<i32> = use_context();
-///    rsx! { "{signal}" }
+///     let signal: Signal<i32> = use_context();
+///     rsx! {
+///         button { onclick: move |_| signal += 1, "increment context" }
+///         p {"{signal}"}
+///     }
 ///}
 /// ```
 pub fn use_context_provider<T: 'static + Clone>(f: impl FnOnce() -> T) -> T {
diff --git a/packages/hooks/src/use_effect.rs b/packages/hooks/src/use_effect.rs
index 97a603b21..0028bc7c5 100644
--- a/packages/hooks/src/use_effect.rs
+++ b/packages/hooks/src/use_effect.rs
@@ -1,7 +1,7 @@
 use dioxus_core::prelude::*;
 use dioxus_signals::ReactiveContext;
 
-/// use_effect will subscribe to any changes in the signal values it captures
+/// `use_effect` will subscribe to any changes in the signal values it captures
 /// effects will always run after first mount and then whenever the signal values change
 /// If the use_effect call was skipped due to an early return, the effect will no longer activate.
 /// ```rust
diff --git a/packages/hooks/src/use_future.rs b/packages/hooks/src/use_future.rs
index d2619f624..a4f6ed214 100644
--- a/packages/hooks/src/use_future.rs
+++ b/packages/hooks/src/use_future.rs
@@ -8,17 +8,17 @@ use dioxus_signals::*;
 use dioxus_signals::{Readable, Writable};
 use std::future::Future;
 
-/// A hook that allows you to spawn a future
-///
+/// A hook that allows you to spawn a future.
+/// This future will **not** run on the server
 /// The future is spawned on the next call to `flush_sync` which means that it will not run on the server.
 /// To run a future on the server, you should use `spawn` directly.
-/// use_future assumes your future will never complete - **it won't return a value**.
+/// `use_future` assumes your future will never complete - **it won't return a value**.
 /// If you want to return a value, use `use_resource` instead.
 /// ```rust
 /// fn app() -> Element {
 ///     let mut count = use_signal(|| 0);
 ///     let mut running = use_signal(|| true);
-///     // use_future will spawn an infinitely running future that can be started and stopped
+///     // `use_future` will spawn an infinitely running future that can be started and stopped
 ///     use_future(move || async move {
 ///         loop {
 ///            if running() {

From 70136b22ea2d9aeeaf2bbbaa260608194589373b Mon Sep 17 00:00:00 2001
From: andrey <agrey0175@proton.me>
Date: Wed, 28 Feb 2024 11:42:04 +0800
Subject: [PATCH 4/6] Fix error in examples/future.rs comments, use_futures
 inline docs comments, also added clarification that Signal<T>.read() and
 Singal<T>() are the same thing

---
 examples/future.rs                           |  4 ++--
 examples/seven_guis/cells.rs                 | 22 +++++++++++++++++
 examples/seven_guis/circle-drawer.rs         | 22 +++++++++++++++++
 examples/seven_guis/counter.rs               | 25 ++++++++++++++++++++
 examples/seven_guis/crud.rs                  | 22 +++++++++++++++++
 examples/seven_guis/flight-booker.rs         | 22 +++++++++++++++++
 examples/seven_guis/temperature-converter.rs | 22 +++++++++++++++++
 examples/seven_guis/timer.rs                 | 22 +++++++++++++++++
 packages/hooks/src/use_context.rs            |  2 +-
 packages/hooks/src/use_future.rs             |  2 +-
 packages/signals/src/read.rs                 |  4 +++-
 11 files changed, 164 insertions(+), 5 deletions(-)
 create mode 100644 examples/seven_guis/cells.rs
 create mode 100644 examples/seven_guis/circle-drawer.rs
 create mode 100644 examples/seven_guis/counter.rs
 create mode 100644 examples/seven_guis/crud.rs
 create mode 100644 examples/seven_guis/flight-booker.rs
 create mode 100644 examples/seven_guis/temperature-converter.rs
 create mode 100644 examples/seven_guis/timer.rs

diff --git a/examples/future.rs b/examples/future.rs
index 130d526b2..76b6c8e7f 100644
--- a/examples/future.rs
+++ b/examples/future.rs
@@ -1,7 +1,7 @@
 //! A simple example that shows how to use the use_future hook to run a background task.
 //!
-//! use_future assumes your future will never complete - it won't return a value.
-//! If you want to return a value, use use_resource instead.
+//! use_future won't return a value, analagous to use_effect.
+//! If you want to return a value from a future, use use_resource instead.
 
 use dioxus::prelude::*;
 use std::time::Duration;
diff --git a/examples/seven_guis/cells.rs b/examples/seven_guis/cells.rs
new file mode 100644
index 000000000..ee33c2230
--- /dev/null
+++ b/examples/seven_guis/cells.rs
@@ -0,0 +1,22 @@
+//! The simplest example of a Dioxus app.
+//!
+//! In this example we:
+//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
+//! - define a main function that calls the launch function with our app function
+//! - define an app function that returns a div element with the text "Hello, world!"
+//!
+//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
+//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
+//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+fn app() -> Element {
+    rsx! {
+        div { "Hello, world!" }
+    }
+}
diff --git a/examples/seven_guis/circle-drawer.rs b/examples/seven_guis/circle-drawer.rs
new file mode 100644
index 000000000..ee33c2230
--- /dev/null
+++ b/examples/seven_guis/circle-drawer.rs
@@ -0,0 +1,22 @@
+//! The simplest example of a Dioxus app.
+//!
+//! In this example we:
+//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
+//! - define a main function that calls the launch function with our app function
+//! - define an app function that returns a div element with the text "Hello, world!"
+//!
+//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
+//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
+//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+fn app() -> Element {
+    rsx! {
+        div { "Hello, world!" }
+    }
+}
diff --git a/examples/seven_guis/counter.rs b/examples/seven_guis/counter.rs
new file mode 100644
index 000000000..12fafb4f9
--- /dev/null
+++ b/examples/seven_guis/counter.rs
@@ -0,0 +1,25 @@
+//! The simplest example of a Dioxus app.
+//!
+//! In this example we:
+//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
+//! - define a main function that calls the launch function with our app function
+//! - define an app function that returns a div element with the text "Hello, world!"
+//!
+//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
+//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
+//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+fn app() -> Element {
+    let counter = use_signal(|| 0usize);
+
+    rsx! {
+        button { onclick: move || counter += 1, "Increment Counter" }
+        p { "{counter}" }
+    }
+}
diff --git a/examples/seven_guis/crud.rs b/examples/seven_guis/crud.rs
new file mode 100644
index 000000000..ee33c2230
--- /dev/null
+++ b/examples/seven_guis/crud.rs
@@ -0,0 +1,22 @@
+//! The simplest example of a Dioxus app.
+//!
+//! In this example we:
+//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
+//! - define a main function that calls the launch function with our app function
+//! - define an app function that returns a div element with the text "Hello, world!"
+//!
+//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
+//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
+//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+fn app() -> Element {
+    rsx! {
+        div { "Hello, world!" }
+    }
+}
diff --git a/examples/seven_guis/flight-booker.rs b/examples/seven_guis/flight-booker.rs
new file mode 100644
index 000000000..ee33c2230
--- /dev/null
+++ b/examples/seven_guis/flight-booker.rs
@@ -0,0 +1,22 @@
+//! The simplest example of a Dioxus app.
+//!
+//! In this example we:
+//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
+//! - define a main function that calls the launch function with our app function
+//! - define an app function that returns a div element with the text "Hello, world!"
+//!
+//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
+//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
+//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+fn app() -> Element {
+    rsx! {
+        div { "Hello, world!" }
+    }
+}
diff --git a/examples/seven_guis/temperature-converter.rs b/examples/seven_guis/temperature-converter.rs
new file mode 100644
index 000000000..ee33c2230
--- /dev/null
+++ b/examples/seven_guis/temperature-converter.rs
@@ -0,0 +1,22 @@
+//! The simplest example of a Dioxus app.
+//!
+//! In this example we:
+//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
+//! - define a main function that calls the launch function with our app function
+//! - define an app function that returns a div element with the text "Hello, world!"
+//!
+//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
+//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
+//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+fn app() -> Element {
+    rsx! {
+        div { "Hello, world!" }
+    }
+}
diff --git a/examples/seven_guis/timer.rs b/examples/seven_guis/timer.rs
new file mode 100644
index 000000000..ee33c2230
--- /dev/null
+++ b/examples/seven_guis/timer.rs
@@ -0,0 +1,22 @@
+//! The simplest example of a Dioxus app.
+//!
+//! In this example we:
+//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
+//! - define a main function that calls the launch function with our app function
+//! - define an app function that returns a div element with the text "Hello, world!"
+//!
+//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
+//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
+//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
+
+use dioxus::prelude::*;
+
+fn main() {
+    launch(app);
+}
+
+fn app() -> Element {
+    rsx! {
+        div { "Hello, world!" }
+    }
+}
diff --git a/packages/hooks/src/use_context.rs b/packages/hooks/src/use_context.rs
index 27c586e4f..9194dbd2f 100644
--- a/packages/hooks/src/use_context.rs
+++ b/packages/hooks/src/use_context.rs
@@ -42,7 +42,7 @@ pub fn use_context<T: 'static + Clone>() -> T {
 ///    use_context_provider(|| Signal::new(0));
 ///    rsx! { Child {} }
 ///}
-// This component does read from the signal, so when the signal changes it will rerun
+/// // This component does read from the signal, so when the signal changes it will rerun
 ///#[component]
 ///fn Child() -> Element {
 ///     let signal: Signal<i32> = use_context();
diff --git a/packages/hooks/src/use_future.rs b/packages/hooks/src/use_future.rs
index a4f6ed214..b2276147b 100644
--- a/packages/hooks/src/use_future.rs
+++ b/packages/hooks/src/use_future.rs
@@ -12,7 +12,7 @@ use std::future::Future;
 /// This future will **not** run on the server
 /// The future is spawned on the next call to `flush_sync` which means that it will not run on the server.
 /// To run a future on the server, you should use `spawn` directly.
-/// `use_future` assumes your future will never complete - **it won't return a value**.
+/// `use_future` **won't return a value**.
 /// If you want to return a value, use `use_resource` instead.
 /// ```rust
 /// fn app() -> Element {
diff --git a/packages/signals/src/read.rs b/packages/signals/src/read.rs
index 63de45047..7effa39f7 100644
--- a/packages/signals/src/read.rs
+++ b/packages/signals/src/read.rs
@@ -39,7 +39,9 @@ pub trait Readable {
         MappedSignal::new(try_read, peek)
     }
 
-    /// Get the current value of the state. If this is a signal, this will subscribe the current scope to the signal. If the value has been dropped, this will panic.
+    /// Get the current value of the state. If this is a signal, this will subscribe the current scope to the signal.
+    /// If the value has been dropped, this will panic. Calling this on a Signal is the same as
+    /// using the signal() syntax to read and subscribe to its value
     #[track_caller]
     fn read(&self) -> ReadableRef<Self> {
         self.try_read().unwrap()

From c9f04ac3d0340a8a42edf5305430293b2c744291 Mon Sep 17 00:00:00 2001
From: andrey <agrey0175@proton.me>
Date: Wed, 28 Feb 2024 11:45:08 +0800
Subject: [PATCH 5/6] remove things that werent meant to be in last commit

---
 examples/seven_guis/cells.rs                 | 22 -----------------
 examples/seven_guis/circle-drawer.rs         | 22 -----------------
 examples/seven_guis/counter.rs               | 25 --------------------
 examples/seven_guis/crud.rs                  | 22 -----------------
 examples/seven_guis/flight-booker.rs         | 22 -----------------
 examples/seven_guis/temperature-converter.rs | 22 -----------------
 examples/seven_guis/timer.rs                 | 22 -----------------
 7 files changed, 157 deletions(-)
 delete mode 100644 examples/seven_guis/cells.rs
 delete mode 100644 examples/seven_guis/circle-drawer.rs
 delete mode 100644 examples/seven_guis/counter.rs
 delete mode 100644 examples/seven_guis/crud.rs
 delete mode 100644 examples/seven_guis/flight-booker.rs
 delete mode 100644 examples/seven_guis/temperature-converter.rs
 delete mode 100644 examples/seven_guis/timer.rs

diff --git a/examples/seven_guis/cells.rs b/examples/seven_guis/cells.rs
deleted file mode 100644
index ee33c2230..000000000
--- a/examples/seven_guis/cells.rs
+++ /dev/null
@@ -1,22 +0,0 @@
-//! The simplest example of a Dioxus app.
-//!
-//! In this example we:
-//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
-//! - define a main function that calls the launch function with our app function
-//! - define an app function that returns a div element with the text "Hello, world!"
-//!
-//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
-//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
-//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
-
-use dioxus::prelude::*;
-
-fn main() {
-    launch(app);
-}
-
-fn app() -> Element {
-    rsx! {
-        div { "Hello, world!" }
-    }
-}
diff --git a/examples/seven_guis/circle-drawer.rs b/examples/seven_guis/circle-drawer.rs
deleted file mode 100644
index ee33c2230..000000000
--- a/examples/seven_guis/circle-drawer.rs
+++ /dev/null
@@ -1,22 +0,0 @@
-//! The simplest example of a Dioxus app.
-//!
-//! In this example we:
-//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
-//! - define a main function that calls the launch function with our app function
-//! - define an app function that returns a div element with the text "Hello, world!"
-//!
-//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
-//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
-//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
-
-use dioxus::prelude::*;
-
-fn main() {
-    launch(app);
-}
-
-fn app() -> Element {
-    rsx! {
-        div { "Hello, world!" }
-    }
-}
diff --git a/examples/seven_guis/counter.rs b/examples/seven_guis/counter.rs
deleted file mode 100644
index 12fafb4f9..000000000
--- a/examples/seven_guis/counter.rs
+++ /dev/null
@@ -1,25 +0,0 @@
-//! The simplest example of a Dioxus app.
-//!
-//! In this example we:
-//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
-//! - define a main function that calls the launch function with our app function
-//! - define an app function that returns a div element with the text "Hello, world!"
-//!
-//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
-//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
-//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
-
-use dioxus::prelude::*;
-
-fn main() {
-    launch(app);
-}
-
-fn app() -> Element {
-    let counter = use_signal(|| 0usize);
-
-    rsx! {
-        button { onclick: move || counter += 1, "Increment Counter" }
-        p { "{counter}" }
-    }
-}
diff --git a/examples/seven_guis/crud.rs b/examples/seven_guis/crud.rs
deleted file mode 100644
index ee33c2230..000000000
--- a/examples/seven_guis/crud.rs
+++ /dev/null
@@ -1,22 +0,0 @@
-//! The simplest example of a Dioxus app.
-//!
-//! In this example we:
-//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
-//! - define a main function that calls the launch function with our app function
-//! - define an app function that returns a div element with the text "Hello, world!"
-//!
-//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
-//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
-//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
-
-use dioxus::prelude::*;
-
-fn main() {
-    launch(app);
-}
-
-fn app() -> Element {
-    rsx! {
-        div { "Hello, world!" }
-    }
-}
diff --git a/examples/seven_guis/flight-booker.rs b/examples/seven_guis/flight-booker.rs
deleted file mode 100644
index ee33c2230..000000000
--- a/examples/seven_guis/flight-booker.rs
+++ /dev/null
@@ -1,22 +0,0 @@
-//! The simplest example of a Dioxus app.
-//!
-//! In this example we:
-//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
-//! - define a main function that calls the launch function with our app function
-//! - define an app function that returns a div element with the text "Hello, world!"
-//!
-//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
-//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
-//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
-
-use dioxus::prelude::*;
-
-fn main() {
-    launch(app);
-}
-
-fn app() -> Element {
-    rsx! {
-        div { "Hello, world!" }
-    }
-}
diff --git a/examples/seven_guis/temperature-converter.rs b/examples/seven_guis/temperature-converter.rs
deleted file mode 100644
index ee33c2230..000000000
--- a/examples/seven_guis/temperature-converter.rs
+++ /dev/null
@@ -1,22 +0,0 @@
-//! The simplest example of a Dioxus app.
-//!
-//! In this example we:
-//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
-//! - define a main function that calls the launch function with our app function
-//! - define an app function that returns a div element with the text "Hello, world!"
-//!
-//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
-//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
-//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
-
-use dioxus::prelude::*;
-
-fn main() {
-    launch(app);
-}
-
-fn app() -> Element {
-    rsx! {
-        div { "Hello, world!" }
-    }
-}
diff --git a/examples/seven_guis/timer.rs b/examples/seven_guis/timer.rs
deleted file mode 100644
index ee33c2230..000000000
--- a/examples/seven_guis/timer.rs
+++ /dev/null
@@ -1,22 +0,0 @@
-//! The simplest example of a Dioxus app.
-//!
-//! In this example we:
-//! - import a number of important items from the prelude (launch, Element, rsx, div, etc.)
-//! - define a main function that calls the launch function with our app function
-//! - define an app function that returns a div element with the text "Hello, world!"
-//!
-//! The `launch` function is the entry point for all Dioxus apps. It takes a function that returns an Element. This function
-//! calls "launch" on the currently-configured renderer you have. So if the `web` feature is enabled, it will launch a web
-//! app, and if the `desktop` feature is enabled, it will launch a desktop app.
-
-use dioxus::prelude::*;
-
-fn main() {
-    launch(app);
-}
-
-fn app() -> Element {
-    rsx! {
-        div { "Hello, world!" }
-    }
-}

From 1404009edc4c6a6a2fbac4cd39bb5f6b6498d4b4 Mon Sep 17 00:00:00 2001
From: Andrey <146410045+agreyyy@users.noreply.github.com>
Date: Wed, 28 Feb 2024 03:48:52 +0000
Subject: [PATCH 6/6] touchups

---
 packages/hooks/src/use_future.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/hooks/src/use_future.rs b/packages/hooks/src/use_future.rs
index b2276147b..53a67087c 100644
--- a/packages/hooks/src/use_future.rs
+++ b/packages/hooks/src/use_future.rs
@@ -13,7 +13,7 @@ use std::future::Future;
 /// The future is spawned on the next call to `flush_sync` which means that it will not run on the server.
 /// To run a future on the server, you should use `spawn` directly.
 /// `use_future` **won't return a value**.
-/// If you want to return a value, use `use_resource` instead.
+/// If you want to return a value from a future, use `use_resource` instead.
 /// ```rust
 /// fn app() -> Element {
 ///     let mut count = use_signal(|| 0);