Added basic docstrings

Author: sfisol

CHANGES.md

@@ -1,9 +1,15 @@
 # Changes
 
-## Unreleased
+## 0.1.0-beta.1 - 2021-12-10
 
 ### Added
 * Re-exports for AutoMap, Computed, Value, DropResource
+* Tutorial
+* Some docstrings with examples
+
+### Changed
+* LazyCache::force_update - Added parameter with_loading
+* Simplified computed refresh function
 
 ## 0.1.0-alpha.3 - 2021-11-29
 

crates/vertigo-browserdriver/src/driver_browser.rs

@@ -22,8 +22,8 @@ use vertigo::FetchResult;
 use vertigo::InstantType;
 use vertigo::RealDomId;
 use vertigo::RefsContext;
-use vertigo::WebcocketMessageDriver;
-use vertigo::computed::Dependencies;
+use vertigo::WebsocketMessageDriver;
+use vertigo::Dependencies;
 use vertigo::utils::DropResource;
 
 struct DriverBrowserInner {
@@ -153,7 +153,7 @@ impl DriverTrait for DriverBrowser {
         js_instant::now().round() as InstantType
     }
 
-    fn websocket(&self, host: String, callback: Box<dyn Fn(WebcocketMessageDriver)>) -> DropResource {
+    fn websocket(&self, host: String, callback: Box<dyn Fn(WebsocketMessageDriver)>) -> DropResource {
         self.driver.driver_websocket.websocket_start(host, callback)
     }
 

crates/vertigo-browserdriver/src/modules/dom/driver_browser_dom.rs

@@ -3,7 +3,7 @@ use vertigo::utils::BoxRefCell;
 use wasm_bindgen::prelude::Closure;
 use std::rc::Rc;
 
-use vertigo::{EventCallback, KeyDownEvent, RealDomId, computed::Dependencies};
+use vertigo::{EventCallback, KeyDownEvent, RealDomId, Dependencies};
 
 use super::driver_dom_command::DriverDomCommand;
 use super::js_dom::DriverBrowserDomJs;

crates/vertigo-browserdriver/src/modules/dom/visited_node_manager.rs

@@ -1,7 +1,7 @@
 use std::rc::Rc;
 use std::collections::HashMap;
 
-use vertigo::{RealDomId, computed::Dependencies, utils::BoxRefCell};
+use vertigo::{RealDomId, Dependencies, utils::BoxRefCell};
 
 use super::driver_data::DriverData;
 

crates/vertigo-browserdriver/src/modules/websocket/websocket.rs

@@ -1,14 +1,14 @@
 use std::rc::Rc;
 use wasm_bindgen::closure::Closure;
 
-use vertigo::{WebcocketMessageDriver, utils::DropResource};
+use vertigo::{WebsocketMessageDriver, utils::DropResource};
 use crate::modules::websocket::js_websocket::DriverWebsocketJs;
 use crate::utils::callback_manager::CallbackManagerOwner;
 use vertigo::utils::BoxRefCell;
 
 #[derive(Clone)]
 struct Callback {
-    stack: Rc<BoxRefCell<CallbackManagerOwner<WebcocketMessageDriver>>>,
+    stack: Rc<BoxRefCell<CallbackManagerOwner<WebsocketMessageDriver>>>,
 }
 
 impl Callback {
@@ -18,7 +18,7 @@ impl Callback {
         }
     }
 
-    pub fn register(&self, callback: Box<dyn Fn(WebcocketMessageDriver)>) -> u64 {
+    pub fn register(&self, callback: Box<dyn Fn(WebsocketMessageDriver)>) -> u64 {
         self.stack.change(callback, |state, callback| {
             state.set(callback)
         })
@@ -30,7 +30,7 @@ impl Callback {
         });
     }
 
-    pub fn trigger_callback(&self, callback_id: u64, message: WebcocketMessageDriver) {
+    pub fn trigger_callback(&self, callback_id: u64, message: WebsocketMessageDriver) {
         self.stack.get_with_context((callback_id, message), |state, (callback_id, message)| {
             state.trigger(callback_id, message);
         });
@@ -52,21 +52,21 @@ impl DriverWebsocket {
         let callback_socket = {
             let callback = callback.clone();
             Closure::new(move |callback_id: u64| {
-                callback.trigger_callback(callback_id, WebcocketMessageDriver::Connection { callback_id });
+                callback.trigger_callback(callback_id, WebsocketMessageDriver::Connection { callback_id });
             })
         };
 
         let callback_message = {
             let callback = callback.clone();
             Closure::new(move |callback_id: u64, message: String| {
-                callback.trigger_callback(callback_id, WebcocketMessageDriver::Message(message));
+                callback.trigger_callback(callback_id, WebsocketMessageDriver::Message(message));
             })
         };
 
         let callback_close = {
             let callback = callback.clone();
             Closure::new(move |callback_id: u64| {
-                callback.trigger_callback(callback_id, WebcocketMessageDriver::Close);
+                callback.trigger_callback(callback_id, WebsocketMessageDriver::Close);
             })
         };
 
@@ -85,7 +85,7 @@ impl DriverWebsocket {
         }
     }
 
-    pub fn websocket_start(&self, host: String, callback: Box<dyn Fn(WebcocketMessageDriver)>) -> DropResource {
+    pub fn websocket_start(&self, host: String, callback: Box<dyn Fn(WebsocketMessageDriver)>) -> DropResource {
         let callback_id = self.callback.register(callback);
         self.driver_js.register_callback(host, callback_id);
 

crates/vertigo/src/app.rs

@@ -11,14 +11,14 @@ use crate::{
     driver::Driver,
 };
 
+/// Starting point of the app. Given the driver and root component of the app,
+/// it creates necessary vertigo facilities and runs a never-ending future of reactivity.
 pub async fn start_app(driver: Driver, computed: VDomComponent) {
     let css_manager = CssManager::new(&driver);
     let root = RealDomElement::create_with_id(driver.clone(), RealDomId::root());
 
-    let subscription = render_to_node(driver.clone(), css_manager.clone(), root, computed);
+    let _subscription = render_to_node(driver.clone(), css_manager.clone(), root, computed);
     driver.flush_update();
 
-    std::future::pending::<()>().await;
-
-    subscription.off();
+    std::future::pending::<()>().await
 }

crates/vertigo/src/computed/auto_map.rs

@@ -11,6 +11,17 @@ use crate::utils::{
 
 type CreateType<K, V> = EqBox<Box<dyn Fn(&K) -> V>>;
 
+/// A structure similar to HashMap
+/// but allows to provide a function `create` for creating a new value if particular key doesn't exists.
+///
+/// Such a function can for example [fetch](struct.Driver.html#method.fetch) data from internet.
+///
+/// ```rust
+/// use vertigo::AutoMap;
+///
+/// let my_map = AutoMap::<i32, i32>::new(|x| x*2);
+/// assert_eq!(my_map.get_value(&5), 10);
+/// ```
 #[derive(PartialEq, Clone)]
 pub struct AutoMap<K: Eq + Hash + Clone, V: PartialEq + Clone + 'static> {
     create: Rc<CreateType<K, V>>,

crates/vertigo/src/computed/client.rs

@@ -45,9 +45,6 @@ impl Client {
         }
     }
 
-    pub fn off(self: Client) {
-    }
-
     pub fn id(&self) -> GraphId {
         self.graph_value.id()
     }

crates/vertigo/src/computed/computed_box.rs

@@ -10,6 +10,45 @@ use crate::{
     }
 };
 
+/// A reactive value that is read-only and computed by dependency graph.
+///
+/// ## Computed directly from Value
+///
+/// ```rust
+/// use vertigo::{Computed, Dependencies};
+///
+/// let deps = Dependencies::default();
+///
+/// let value = deps.new_value(5);
+///
+/// let comp = value.to_computed();
+///
+/// assert_eq!(*comp.get_value(), 5);
+///
+/// // Can't do that
+/// // comp.set_value(10);
+/// ```
+///
+/// ## Computed from Value by provided function
+///
+/// ```rust
+/// use vertigo::{Computed, Dependencies};
+///
+/// let deps = Dependencies::default();
+///
+/// let value = deps.new_value(2);
+///
+/// let comp_2 = {
+///     let v = value.clone();
+///     deps.from(move || *v.get_value() * 2)
+/// };
+///
+/// assert_eq!(*comp_2.get_value(), 4);
+///
+/// value.set_value(6);
+///
+/// assert_eq!(*comp_2.get_value(), 12);
+/// ```
 pub struct Computed<T: PartialEq + 'static> {
     inner: GraphValue<T>,
 }

crates/vertigo/src/computed/graph_value.rs

@@ -256,18 +256,6 @@ impl<T: PartialEq + 'static> GraphValue<T> {
         GraphValue::new(deps, GraphValueType::Client, get_value)
     }
 
-    pub fn is_computed(&self) -> bool {
-        self.inner.inner.get(|state| {
-            state.value_type == GraphValueType::Computed
-        })
-    }
-
-    pub fn is_client(&self) -> bool {
-        self.inner.inner.get(|state| {
-            state.value_type == GraphValueType::Client
-        })
-    }
-
     pub fn get_value(&self, is_computed: bool) -> Rc<T> {
         self.inner.inner.change(is_computed, |state, is_computed| {
             state.get_value(is_computed)

crates/vertigo/src/computed/value.rs

@@ -53,7 +53,24 @@ impl<T: PartialEq + 'static> Drop for ValueInner<T> {
     }
 }
 
-
+/// A reactive value. Basic building block of app state.
+///
+/// Can be read or written.
+///
+/// ```rust
+/// use vertigo::{Computed, Dependencies};
+///
+/// let deps = Dependencies::default();
+///
+/// let value = deps.new_value(5);
+///
+/// assert_eq!(*value.get_value(), 5);
+///
+/// value.set_value(10);
+///
+/// assert_eq!(*value.get_value(), 10);
+/// ```
+///
 pub struct Value<T: PartialEq + 'static> {
     inner: Rc<BoxRefCell<ValueInner<T>>>,
     pub deps: Dependencies,