swaits/dioxus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve inline docs (#2460)

Browse Source 
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
This commit is contained in:
Evan Almloff authored and GitHub committed 2024-06-06 18:15:17 -07:00
1 parent 054351139f
commit 0127501dbf
71 files changed
+4132 -1162
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/html/src/elements.rs
+236 -46
View File
@@ -13,37 +13,147 @@ pub type AttributeDiscription = (&'static str, Option<&'static str>, bool);
macro_rules! impl_attribute {
(
$(#[$attr_method:meta])*
$fil:ident: $vil:ident (DEFAULT),
$element:ident {
$(#[$attr_method:meta])*
$fil:ident: $vil:ident (DEFAULT),
}
) => {
$(#[$attr_method])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
#[doc = concat!("let ", stringify!($fil), " = \"value\";")]
///
/// rsx! {
/// // Attributes need to be under the element they modify
#[doc = concat!(" ", stringify!($element), " {")]
/// // Attributes are followed by a colon and then the value of the attribute
#[doc = concat!(" ", stringify!($fil), ": \"value\"")]
/// }
#[doc = concat!(" ", stringify!($element), " {")]
/// // Or you can use the shorthand syntax if you have a variable in scope that has the same name as the attribute
#[doc = concat!(" ", stringify!($fil), ",")]
/// }
/// };
/// ```
pub const $fil: AttributeDiscription = (stringify!($fil), None, false);
};
(
$(#[$attr_method:meta])*
$fil:ident: $vil:ident ($name:literal),
$element:ident {
$(#[$attr_method:meta])*
$fil:ident: $vil:ident ($name:literal),
}
) => {
$(#[$attr_method])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
#[doc = concat!("let ", stringify!($fil), " = \"value\";")]
///
/// rsx! {
/// // Attributes need to be under the element they modify
#[doc = concat!(" ", stringify!($element), " {")]
/// // Attributes are followed by a colon and then the value of the attribute
#[doc = concat!(" ", stringify!($fil), ": \"value\"")]
/// }
#[doc = concat!(" ", stringify!($element), " {")]
/// // Or you can use the shorthand syntax if you have a variable in scope that has the same name as the attribute
#[doc = concat!(" ", stringify!($fil), ",")]
/// }
/// };
/// ```
pub const $fil: AttributeDiscription = ($name, None, false);
};
(
$(#[$attr_method:meta])*
$fil:ident: $vil:ident (volatile),
$element:ident {
$(#[$attr_method:meta])*
$fil:ident: $vil:ident (volatile),
}
) => {
$(#[$attr_method])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
#[doc = concat!("let ", stringify!($fil), " = \"value\";")]
///
/// rsx! {
/// // Attributes need to be under the element they modify
#[doc = concat!(" ", stringify!($element), " {")]
/// // Attributes are followed by a colon and then the value of the attribute
#[doc = concat!(" ", stringify!($fil), ": \"value\"")]
/// }
#[doc = concat!(" ", stringify!($element), " {")]
/// // Or you can use the shorthand syntax if you have a variable in scope that has the same name as the attribute
#[doc = concat!(" ", stringify!($fil), ",")]
/// }
/// };
/// ```
pub const $fil: AttributeDiscription = (stringify!($fil), None, true);
};
(
$(#[$attr_method:meta])*
$fil:ident: $vil:ident (in $ns:literal),
$element:ident {
$(#[$attr_method:meta])*
$fil:ident: $vil:ident (in $ns:literal),
}
) => {
$(#[$attr_method])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
#[doc = concat!("let ", stringify!($fil), " = \"value\";")]
///
/// rsx! {
/// // Attributes need to be under the element they modify
#[doc = concat!(" ", stringify!($element), " {")]
/// // Attributes are followed by a colon and then the value of the attribute
#[doc = concat!(" ", stringify!($fil), ": \"value\"")]
/// }
#[doc = concat!(" ", stringify!($element), " {")]
/// // Or you can use the shorthand syntax if you have a variable in scope that has the same name as the attribute
#[doc = concat!(" ", stringify!($fil), ",")]
/// }
/// };
/// ```
pub const $fil: AttributeDiscription = (stringify!($fil), Some($ns), false)
};
(
$(#[$attr_method:meta])*
$fil:ident: $vil:ident (in $ns:literal : volatile),
$element:ident {
$(#[$attr_method:meta])*
$fil:ident: $vil:ident (in $ns:literal : volatile),
}
) => {
$(#[$attr_method])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
#[doc = concat!("let ", stringify!($fil), " = \"value\";")]
///
/// rsx! {
/// // Attributes need to be under the element they modify
#[doc = concat!(" ", stringify!($element), " {")]
/// // Attributes are followed by a colon and then the value of the attribute
#[doc = concat!(" ", stringify!($fil), ": \"value\"")]
/// }
#[doc = concat!(" ", stringify!($element), " {")]
/// // Or you can use the shorthand syntax if you have a variable in scope that has the same name as the attribute
#[doc = concat!(" ", stringify!($fil), ",")]
/// }
/// };
/// ```
pub const $fil: AttributeDiscription = (stringify!($fil), Some($ns), true)
};
}
@@ -114,6 +224,30 @@ macro_rules! impl_element {
) => {
#[allow(non_camel_case_types)]
$(#[$attr])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # let attributes = vec![];
/// # fn ChildComponent() -> Element { todo!() }
/// # let raw_expression: Element = rsx! {};
/// rsx! {
/// // Elements are followed by braces that surround any attributes and children for that element
#[doc = concat!(" ", stringify!($name), " {")]
/// // Add any attributes first
/// class: "my-class",
/// "custom-attribute-name": "value",
/// // Then add any attributes you are spreading into this element
/// ..attributes,
/// // Then add any children elements, components, text nodes, or raw expressions
/// div {}
/// ChildComponent {}
/// "child text"
/// {raw_expression}
/// }
/// };
/// ```
pub mod $name {
#[allow(unused)]
use super::*;
@@ -124,8 +258,10 @@ macro_rules! impl_element {
$(
impl_attribute!(
$(#[$attr_method])*
$fil: $vil ($extra),
$name {
$(#[$attr_method])*
$fil: $vil ($extra),
}
);
)*
}
@@ -141,6 +277,30 @@ macro_rules! impl_element {
}
) => {
$(#[$attr])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # let attributes = vec![];
/// # fn ChildComponent() -> Element { todo!() }
/// # let raw_expression: Element = rsx! {};
/// rsx! {
/// // Elements are followed by braces that surround any attributes and children for that element
#[doc = concat!(" ", stringify!($name), " {")]
/// // Add any attributes first
/// color: "red",
/// "custom-attribute-name": "value",
/// // Then add any attributes you are spreading into this element
/// ..attributes,
/// // Then add any children elements, components, text nodes, or raw expressions
/// circle { cx: "10", cy: "10", r: "2", fill: "red" }
/// ChildComponent {}
/// "child text"
/// {raw_expression}
/// }
/// };
/// ```
pub mod $name {
#[allow(unused)]
use super::*;
@@ -151,8 +311,10 @@ macro_rules! impl_element {
$(
impl_attribute!(
$(#[$attr_method])*
$fil: $vil ($extra),
$name {
$(#[$attr_method])*
$fil: $vil ($extra),
}
);
)*
}
@@ -169,6 +331,30 @@ macro_rules! impl_element {
) => {
#[allow(non_camel_case_types)]
$(#[$attr])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # let attributes = vec![];
/// # fn ChildComponent() -> Element { todo!() }
/// # let raw_expression: Element = rsx! {};
/// rsx! {
/// // Elements are followed by braces that surround any attributes and children for that element
#[doc = concat!(" ", stringify!($element), " {")]
/// // Add any attributes first
/// color: "red",
/// "custom-attribute-name": "value",
/// // Then add any attributes you are spreading into this element
/// ..attributes,
/// // Then add any children elements, components, text nodes, or raw expressions
/// circle { cx: "10", cy: "10", r: "2", fill: "red" }
/// ChildComponent {}
/// "child text"
/// {raw_expression}
/// }
/// };
/// ```
pub mod $element {
#[allow(unused)]
use super::*;
@@ -179,8 +365,10 @@ macro_rules! impl_element {
$(
impl_attribute!(
$(#[$attr_method])*
$fil: $vil ($extra),
$element {
$(#[$attr_method])*
$fil: $vil ($extra),
}
);
)*
}
@@ -390,6 +578,30 @@ macro_rules! builder_constructors {
pub enum CompleteWithBraces {
$(
$(#[$attr])*
///
/// ## Usage in rsx
///
/// ```rust, no_run
/// # use dioxus::prelude::*;
/// # let attributes = vec![];
/// # fn ChildComponent() -> Element { todo!() }
/// # let raw_expression: Element = rsx! {};
/// rsx! {
/// // Elements are followed by braces that surround any attributes and children for that element
#[doc = concat!(" ", stringify!($name), " {")]
/// // Add any attributes first
/// class: "my-class",
/// "custom-attribute-name": "value",
/// // Then add any attributes you are spreading into this element
/// ..attributes,
/// // Then add any children elements, components, text nodes, or raw expressions
/// div {}
/// ChildComponent {}
/// "child text"
/// {raw_expression}
/// }
/// };
/// ```
$name {}
),*
}
@@ -521,14 +733,6 @@ builder_constructors! {
/// - The most important heading is `<h1>` and the least important heading is `<h6>`.
/// - The `<h1>` heading is the first heading in the document.
/// - The `<h1>` heading is usually a large bolded font.
///
/// # Usage
///
/// ```rust, ignore
/// html!(<h1> A header element </h1>)
/// rsx!(h1 { "A header element" })
/// LazyNodes::new(|f| f.el(h1).children([f.text("A header element")]).finish())
/// ```
h1 None {};
/// Build a
@@ -541,13 +745,6 @@ builder_constructors! {
/// - The most important heading is `<h1>` and the least important heading is `<h6>`.
/// - The `<h2>` heading is the second heading in the document.
/// - The `<h2>` heading is usually a large bolded font.
///
/// # Usage
/// ```rust, ignore
/// html!(<h2> A header element </h2>)
/// rsx!(h2 { "A header element" })
/// LazyNodes::new(|f| f.el(h2).children([f.text("A header element")]).finish())
/// ```
h2 None {};
/// Build a
@@ -556,10 +753,10 @@ builder_constructors! {
///
/// # About
/// - The HTML <h1> element is found within the <body> tag.
/// - Headings can range from <h1> to <h6>.
/// - The most important heading is <h1> and the least important heading is <h6>.
/// - The <h1> heading is the first heading in the document.
/// - The <h1> heading is usually a large bolded font.
/// - Headings can range from `<h1>` to `<h6>`.
/// - The most important heading is `<h1>`` and the least important heading is `<h6>`.
/// - The `<h1>` heading is the first heading in the document.
/// - The `<h1>` heading is usually a large bolded font.
h3 None {};
/// Build a
@@ -612,20 +809,13 @@ builder_constructors! {
/// Part of the HTML namespace. Only works in HTML-compatible renderers
///
/// ## Definition and Usage
/// - The <div> tag defines a division or a section in an HTML document.
/// - The <div> tag is used as a container for HTML elements - which is then styled with CSS or manipulated with JavaScript.
/// - The <div> tag is easily styled by using the class or id attribute.
/// - Any sort of content can be put inside the <div> tag!
/// - The `<div>` tag defines a division or a section in an HTML document.
/// - The `<div>` tag is used as a container for HTML elements - which is then styled with CSS or manipulated with JavaScript.
/// - The `<div>` tag is easily styled by using the class or id attribute.
/// - Any sort of content can be put inside the `<div>` tag!
///
/// Note: By default, browsers always place a line break before and after the <div> element.
///
/// ## Usage
/// ```rust, ignore
/// html!(<div> A header element </div>)
/// rsx!(div { "A header element" })
/// LazyNodes::new(|f| f.element(div, &[], &[], &[], None))
/// ```
///
/// ## References:
/// - <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div>
/// - <https://www.w3schools.com/tags/tag_div.asp>