Improve inline docs (DioxusLabs#2460)

Improve inline docs

* improve incorrect event handler return error message

* Improve event handler docs

* document the eval functions

* document spawn and common spawn errors

* fix event handler docs

* add notes about how you use attributes and elements in rsx

* add doc aliases for attributes and events we rename

* add some more aliases for common search terms

* don't doc ignore any public examples in core

* don't ignore public doc examples in ssr

* don't ignore examples in the dioxus package readme

* add a warning when you launch without a renderer enabled

* fix some outdated element docs

* add a bunch of examples to resource

* add notes about desktop events

* add more docs for use_resource

* add on_unimplemented hint to Dependency

* fix some unresolved links

* add examples to each of the router traits

* add not implemented errors for router traits

* add an example to the routable trait

* expand rsx macro docs

* improve memo docs

* update the dioxus readme

* mention dioxus crate features in the docs

* fix a bunch of doc tests

* fix html doc tests

* fix router doc tests

* fix dioxus signals doc tests

* fix dioxus ssr doc tests

* fix use_future example in the hooks cheat sheet

* add a javascript alias for eval

* fix hook explanation values

* remove unused embed-doc-image dependency

packages/check/src/metadata.rs

@@ -1,11 +1,11 @@
 #[derive(Debug, Clone, PartialEq, Eq)]
 /// Information about a hook call or function.
 pub struct HookInfo {
-    /// The name of the hook, e.g. `use_state`.
+    /// The name of the hook, e.g. `use_signal`.
     pub name: String,
-    /// The span of the hook, e.g. `use_signal(|| 0)`.
+    /// The span of the hook, e.g. `use_signal`.
     pub span: Span,
-    /// The span of the name, e.g. `use_state`.
+    /// The span of the name, e.g. `use_signal`.
     pub name_span: Span,
 }
 

packages/core-macro/src/lib.rs

@@ -31,6 +31,191 @@ pub fn derive_typed_builder(input: TokenStream) -> TokenStream {
 }
 
 /// The rsx! macro makes it easy for developers to write jsx-style markup in their components.
+///
+/// ## Elements
+///
+/// You can render elements with rsx! with the element name and then braces surrounding the attributes and children.
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// rsx! {
+///     div {
+///         div {}
+///     }
+/// };
+/// ```
+///
+/// <details>
+/// <summary>Web Components</summary>
+///
+///
+/// Dioxus will automatically render any elements with `-` as a untyped web component:
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// rsx! {
+///     div-component {
+///         div {}
+///     }
+/// };
+/// ```
+///
+/// You can wrap your web component in a custom component to add type checking:
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// #[component]
+/// fn MyDivComponent(width: i64) -> Element {
+///     rsx! {
+///         div-component {
+///             "width": width
+///         }
+///     }
+/// }
+/// ```
+///
+///
+/// </details>
+///
+/// ## Attributes
+///
+/// You can add attributes to any element inside the braces. Attributes are key-value pairs separated by a colon.
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// let width = 100;
+/// rsx! {
+///     div {
+///         // Set the class attribute to "my-class"
+///         class: "my-class",
+///         // attribute strings are automatically formatted with the format macro
+///         width: "{width}px",
+///     }
+/// };
+/// ```
+///
+/// ### Optional Attributes
+///
+/// You can include optional attributes with an unterminated if statement as the value of the attribute:
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// # let first_boolean = true;
+/// # let second_boolean = false;
+/// rsx! {
+///     div {
+///         // Set the class attribute to "my-class" if true
+///         class: if first_boolean {
+///             "my-class"
+///         },
+///         // Set the class attribute to "my-other-class" if false
+///         class: if second_boolean {
+///             "my-other-class"
+///         }
+///     }
+/// };
+/// ```
+///
+/// ### Raw Attributes
+///
+/// Dioxus defaults to attributes that are type checked as html. If you want to include an attribute that is not included in the html spec, you can use the `raw` attribute surrounded by quotes:
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// rsx! {
+///     div {
+///         // Set the data-count attribute to "1"
+///         "data-count": "1"
+///     }
+/// };
+/// ```
+///
+/// ## Text
+///
+/// You can include text in your markup as a string literal:
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// let name = "World";
+/// rsx! {
+///     div {
+///         "Hello World"
+///         // Just like attributes, you can included formatted segments inside your text
+///         "Hello {name}"
+///     }
+/// };
+/// ```
+///
+/// ## Components
+///
+/// You can render any [`macro@crate::component`]s you created inside your markup just like elements. Components must either start with a capital letter or contain a `_` character.
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// #[component]
+/// fn HelloWorld() -> Element {
+///     rsx! { "hello world!" }
+/// }
+///
+/// rsx! {
+///     div {
+///         HelloWorld {}
+///     }
+/// };
+/// ```
+///
+/// ## If statements
+///
+/// You can use if statements to conditionally render children. The body of the for if statement is parsed as rsx markup:
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// let first_boolean = true;
+/// let second_boolean = false;
+/// rsx! {
+///     if first_boolean {
+///         div {
+///             "first"
+///         }
+///     }
+///
+///     if second_boolean {
+///         "second"
+///     }
+/// };
+/// ```
+///
+/// ## For loops
+///
+/// You can also use for loops to iterate over a collection of items. The body of the for loop is parsed as rsx markup:
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// let numbers = vec![1, 2, 3];
+/// rsx! {
+///     for number in numbers {
+///         div {
+///             "{number}"
+///         }
+///     }
+/// };
+/// ```
+///
+/// ## Raw Expressions
+///
+/// You can include raw expressions inside your markup inside curly braces. Your expression must implement the [`IntoDynNode`](https://docs.rs/dioxus-core/latest/dioxus_core/trait.IntoDynNode.html) trait:
+///
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
+/// let name = "World";
+/// rsx! {
+///     div {
+///         // Text can be converted into a dynamic node in rsx
+///         {name}
+///     }
+///     // Iterators can also be converted into dynamic nodes
+///     {(0..10).map(|n| n * n).map(|number| rsx! { div { "{number}" } })}
+/// };
+/// ```
 #[proc_macro]
 pub fn rsx(tokens: TokenStream) -> TokenStream {
     match syn::parse::<rsx::CallBody>(tokens) {
@@ -40,8 +225,6 @@ pub fn rsx(tokens: TokenStream) -> TokenStream {
 }
 
 /// The rsx! macro makes it easy for developers to write jsx-style markup in their components.
-///
-/// The render macro automatically renders rsx - making it unhygienic.
 #[deprecated(note = "Use `rsx!` instead.")]
 #[proc_macro]
 pub fn render(tokens: TokenStream) -> TokenStream {
@@ -71,15 +254,17 @@ pub fn render(tokens: TokenStream) -> TokenStream {
 ///
 /// # Examples
 /// * Without props:
-/// ```rust,ignore
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
 /// #[component]
 /// fn GreetBob() -> Element {
 ///     rsx! { "hello, bob" }
 /// }
 /// ```
 ///
 /// * With props:
-/// ```rust,ignore
+/// ```rust, no_run
+/// # use dioxus::prelude::*;
 /// #[component]
 /// fn GreetBob(bob: String) -> Element {
 ///    rsx! { "hello, {bob}" }
@@ -101,21 +286,25 @@ pub fn component(_args: TokenStream, input: TokenStream) -> TokenStream {
 /// you would be repeating a lot of the usual Rust boilerplate.
 ///
 /// # Example
-/// ```rust,ignore
+/// ```rust,no_run
+/// # use dioxus::prelude::*;
 /// #[inline_props]
-/// fn app(bob: String) -> Element {
-///     rsx! { "hello, {bob}") }
+/// fn GreetBob(bob: String) -> Element {
+///     rsx! { "hello, {bob}" }
 /// }
+/// ```
 ///
-/// // is equivalent to
+/// is equivalent to
 ///
-/// #[derive(PartialEq, Props)]
+/// ```rust,no_run
+/// # use dioxus::prelude::*;
+/// #[derive(PartialEq, Props, Clone)]
 /// struct AppProps {
 ///     bob: String,
 /// }
 ///
-/// fn app(props: AppProps) -> Element {
-///     rsx! { "hello, {bob}") }
+/// fn GreetBob(props: AppProps) -> Element {
+///     rsx! { "hello, {props.bob}" }
 /// }
 /// ```
 #[proc_macro_attribute]

packages/core-macro/src/props/mod.rs

@@ -3,8 +3,8 @@
 //! However, it has been adopted to fit the Dioxus Props builder pattern.
 //!
 //! For Dioxus, we make a few changes:
-//! - [x] Automatically implement Into<Option> on the setters (IE the strip setter option)
-//! - [x] Automatically implement a default of none for optional fields (those explicitly wrapped with Option<T>)
+//! - [x] Automatically implement [`Into<Option>`] on the setters (IE the strip setter option)
+//! - [x] Automatically implement a default of none for optional fields (those explicitly wrapped with [`Option<T>`])
 
 use proc_macro2::TokenStream;
 
@@ -533,6 +533,7 @@ mod struct_info {
         pub builder_attr: TypeBuilderAttr,
         pub builder_name: syn::Ident,
         pub conversion_helper_trait_name: syn::Ident,
+        #[allow(unused)]
         pub core: syn::Ident,
     }
 

packages/core/Cargo.toml

@@ -22,6 +22,7 @@ tracing = { workspace = true }
 serde = { version = "1", features = ["derive"], optional = true }
 tracing-subscriber = "0.3.18"
 generational-box = { workspace = true }
+rustversion = "1.0.17"
 
 [dev-dependencies]
 tokio = { workspace = true, features = ["full"] }
@@ -32,6 +33,13 @@ rand = "0.8.5"
 dioxus-ssr = { workspace = true }
 reqwest = { workspace = true}
 
+[dev-dependencies.web-sys]
+version = "0.3.56"
+features = [
+    "Document",
+    "HtmlElement",
+]
+
 [features]
 default = []
 serialize = ["serde"]