code comments for Scheduler and ComponentLink (#1274)

* code comments for Scheduler and ComponentLink

* Fix typos, reformat code, address pr comments

* resolve pull request comments

yew/src/html/scope.rs

@@ -162,7 +162,10 @@ impl<COMP: Component> Scope<COMP> {
         scheduler().push_comp(ComponentRunnableType::Destroy, Box::new(destroy));
     }
 
-    /// Send a message to the component
+    /// Send a message to the component.
+    ///
+    /// Please be aware that currently this method synchronously
+    /// schedules a call to the [Component](Component) interface.
     pub fn send_message<T>(&self, msg: T)
     where
         T: Into<COMP::Message>,
@@ -172,14 +175,22 @@ impl<COMP: Component> Scope<COMP> {
 
     /// Send a batch of messages to the component.
     ///
-    /// This is useful for reducing re-renders of the components because the messages are handled
-    /// together and the view function is called only once if needed.
+    /// This is useful for reducing re-renders of the components
+    /// because the messages are handled together and the view
+    /// function is called only once if needed.
+    ///
+    /// Please be aware that currently this method synchronously
+    /// schedules calls to the [Component](Component) interface.
     pub fn send_message_batch(&self, messages: Vec<COMP::Message>) {
         self.update(ComponentUpdate::MessageBatch(messages), false);
     }
 
-    /// Creates a `Callback` which will send a message to the linked component's
-    /// update method when invoked.
+    /// Creates a `Callback` which will send a message to the linked
+    /// component's update method when invoked.
+    ///
+    /// Please be aware that currently the result of this callback
+    /// synchronously schedules a call to the [Component](Component)
+    /// interface.
     pub fn callback<F, IN, M>(&self, function: F) -> Callback<IN>
     where
         M: Into<COMP::Message>,
@@ -193,8 +204,12 @@ impl<COMP: Component> Scope<COMP> {
         closure.into()
     }
 
-    /// Creates a `Callback` from a FnOnce which will send a message to the linked
-    /// component's update method when invoked.
+    /// Creates a `Callback` from a FnOnce which will send a message
+    /// to the linked component's update method when invoked.
+    ///
+    /// Please be aware that currently the result of this callback
+    /// will synchronously schedule calls to the
+    /// [Component](Component) interface.
     pub fn callback_once<F, IN, M>(&self, function: F) -> Callback<IN>
     where
         M: Into<COMP::Message>,
@@ -208,8 +223,12 @@ impl<COMP: Component> Scope<COMP> {
         Callback::once(closure)
     }
 
-    /// Creates a `Callback` which will send a batch of messages back to the linked
-    /// component's update method when invoked.
+    /// Creates a `Callback` which will send a batch of messages back
+    /// to the linked component's update method when invoked.
+    ///
+    /// Please be aware that currently the results of these callbacks
+    /// will synchronously schedule calls to the
+    /// [Component](Component) interface.
     pub fn batch_callback<F, IN>(&self, function: F) -> Callback<IN>
     where
         F: Fn(IN) -> Vec<COMP::Message> + 'static,
@@ -236,6 +255,8 @@ struct ComponentState<COMP: Component> {
 }
 
 impl<COMP: Component> ComponentState<COMP> {
+    /// Creates a new `ComponentState`, also invokes the `create()`
+    /// method on component to create it.
     fn new(
         parent: Element,
         ancestor: Option<VNode>,
@@ -255,6 +276,9 @@ impl<COMP: Component> ComponentState<COMP> {
     }
 }
 
+/// A `Runnable` task which creates the `ComponentState` (if there is
+/// none) and invokes the `create()` method on a `Component` to create
+/// it.
 struct CreateComponent<COMP>
 where
     COMP: Component,
@@ -285,6 +309,7 @@ where
     }
 }
 
+/// A `Runnable` task which calls the `update()` method on a `Component`.
 struct UpdateComponent<COMP>
 where
     COMP: Component,
@@ -334,6 +359,7 @@ where
     }
 }
 
+/// A `Runnable` task which calls the `rendered()` method on a `Component`.
 struct RenderedComponent<COMP>
 where
     COMP: Component,
@@ -362,6 +388,7 @@ where
     }
 }
 
+/// A `Runnable` task which calls the `destroy()` method on a `Component`.
 struct DestroyComponent<COMP>
 where
     COMP: Component,

yew/src/scheduler.rs

@@ -24,6 +24,7 @@ pub(crate) trait Runnable {
 /// This is a global scheduler suitable to schedule and run any tasks.
 #[derive(Clone)]
 pub(crate) struct Scheduler {
+    /// This lock is used to prevent recursion in [Scheduler#start()](Scheduler#start())
     lock: Rc<RefCell<()>>,
     main: Shared<VecDeque<Box<dyn Runnable>>>,
     component: ComponentScheduler,
@@ -97,6 +98,9 @@ impl Scheduler {
     }
 
     pub(crate) fn start(&self) {
+        // The lock here is used to prevent recursion. If the lock
+        // here fails to acquire, it is because this `start()` method
+        // is being called recursively in a `runnable.run()`.
         if let Ok(_lock) = self.lock.try_borrow_mut() {
             while let Some(runnable) = self.next_runnable() {
                 runnable.run();