From 1c8b640855d7628c93cf54c6389515fa37b16f9d Mon Sep 17 00:00:00 2001
From: Greg Johnston <greg.johnston@gmail.com>
Date: Wed, 14 Dec 2022 06:44:14 -0500
Subject: [PATCH] Update `#[component]` docs

---
 leptos_macro/src/lib.rs | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/leptos_macro/src/lib.rs b/leptos_macro/src/lib.rs
index 49c65aa53..a67496a6b 100644
--- a/leptos_macro/src/lib.rs
+++ b/leptos_macro/src/lib.rs
@@ -245,23 +245,29 @@ pub fn view(tokens: TokenStream) -> TokenStream {
 
 /// Annotates a function so that it can be used with your template as a Leptos `<Component/>`.
 /// 
-/// The `#[component]` macro allows you to write plain Rust functions that return DOM nodes,
-/// and call them within your Leptos application as if they were custom HTML elements. The 
+/// The `#[component]` macro allows you to annotate plain Rust functions that return [Element](leptos_dom::Element)s,
+/// and use them within your Leptos [view](mod@view) as if they were custom HTML elements. The 
 /// component function takes a [Scope](leptos_reactive::Scope) and any number of other arguments.
 /// When you use the component somewhere else, the names of its arguments are the names
-/// of the properties you use in the [view](mod@view) macro. (The compiler generates a special `Props` type
-/// for each component, which you need to import; see #3 below.)
+/// of the properties you use in the [view](mod@view) macro.
 /// 
-/// In other words, you can write code like this:
+/// Here’s how you would define and use a simple Leptos component which can accept custom properties for a name and age:
 /// ```rust
 /// # use leptos::*;
+/// use std::time::Duration;
+/// 
 /// #[component]
 /// fn HelloComponent(cx: Scope, name: String, age: u8) -> Element {
-///   // do some reactive stuff here
-///   let (name, set_name) = create_signal(cx, name);
+///   // create the signals (reactive values) that will update the UI
+///   let (age, set_age) = create_signal(cx, age);
+///   // increase `age` by 1 every second
+///   set_interval(move || {
+///     set_age.update(|age| *age += 1)
+///   }, Duration::from_secs(1));
 ///   
-///   // return a view
-///   view! { 
+///   // return the user interface, which will be automatically updated
+///   // when signal values change
+///   view! { cx,
 ///     <p>"Your name is " {name} " and you are " {age} " years old."</p>
 ///   }
 /// }
@@ -275,8 +281,12 @@ pub fn view(tokens: TokenStream) -> TokenStream {
 ///   }
 /// }
 /// ```
+/// 
+/// The `#[component]` macro creates a struct with a name like `HelloComponentProps`. If you define
+/// your component in one module and import it into another, make sure you import this `___Props`
+/// struct as well.
 ///
-/// Here are some important things to remember.
+/// Here are some important details about how Leptos components work within the framework:
 /// 1. **The component function only runs once.** Your component function is not a “render” function
 ///    that re-runs whenever changes happen in the state. It’s a “setup” function that runs once to
 ///    create the user interface, and sets up a reactive system to update it. This means it’s okay