document every item in native-core

packages/native-core/src/node.rs

@@ -1,22 +1,36 @@
+//! Items related to Nodes in the RealDom
+
 use rustc_hash::{FxHashMap, FxHashSet};
 use shipyard::Component;
-use std::{any::Any, fmt::Debug};
+use std::{
+    any::Any,
+    fmt::{Debug, Display},
+};
 
+/// A element node in the RealDom
 #[derive(Debug, Clone, Default)]
 pub struct ElementNode<V: FromAnyValue = ()> {
+    /// The [tag](https://developer.mozilla.org/en-US/docs/Web/API/Element/tagName) of the element
     pub tag: String,
+    /// The [namespace](https://developer.mozilla.org/en-US/docs/Web/API/Element/namespaceURI) of the element
     pub namespace: Option<String>,
+    /// The attributes of the element
     pub attributes: FxHashMap<OwnedAttributeDiscription, OwnedAttributeValue<V>>,
+    /// The events the element is listening for
     pub listeners: FxHashSet<String>,
 }
 
+/// A text node in the RealDom
 #[derive(Debug, Clone, Default)]
 pub struct TextNode {
+    /// The text of the node
     pub text: String,
+    /// The events the node is listening for
     pub listeners: FxHashSet<String>,
 }
 
 impl TextNode {
+    /// Create a new text node
     pub fn new(text: String) -> Self {
         Self {
             text,
@@ -25,17 +39,26 @@ impl TextNode {
     }
 }
 
-/// A type of node with data specific to the node type. The types are a subset of the [VNode] types.
+/// A type of node with data specific to the node type.
 #[derive(Debug, Clone, Component)]
 pub enum NodeType<V: FromAnyValue = ()> {
+    /// A text node
     Text(TextNode),
+    /// An element node
     Element(ElementNode<V>),
+    /// A placeholder node. This can be used as a cheaper placeholder for a node that will be created later
     Placeholder,
 }
 
+/// A discription of an attribute on a DOM node, such as `id` or `href`.
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
 pub struct OwnedAttributeDiscription {
+    /// The name of the attribute.
     pub name: String,
+    /// The namespace of the attribute used to identify what kind of attribute it is.
+    ///
+    /// For renderers that use HTML, this can be used to identify if the attribute is a style attribute.
+    /// Instead of parsing the style attribute every time a style is changed, you can set an attribute with the `style` namespace.
     pub namespace: Option<String>,
 }
 
@@ -50,16 +73,24 @@ pub struct OwnedAttributeView<'a, V: FromAnyValue = ()> {
     pub value: &'a OwnedAttributeValue<V>,
 }
 
+/// The value of an attribute on a DOM node. This contains non-text values to allow users to skip parsing attribute values in some cases.
 #[derive(Clone)]
 pub enum OwnedAttributeValue<V: FromAnyValue = ()> {
+    /// A string value. This is the most common type of attribute.
     Text(String),
+    /// A floating point value.
     Float(f64),
+    /// An integer value.
     Int(i64),
+    /// A boolean value.
     Bool(bool),
+    /// A custom value specific to the renderer
     Custom(V),
 }
 
+/// Something that can be converted from a borrowed [Any] value.
 pub trait FromAnyValue: Clone + 'static {
+    /// Convert from an [Any] value.
     fn from_any_value(value: &dyn Any) -> Self;
 }
 
@@ -79,6 +110,18 @@ impl<V: FromAnyValue> Debug for OwnedAttributeValue<V> {
     }
 }
 
+impl<V: FromAnyValue + Display> Display for OwnedAttributeValue<V> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Text(arg0) => f.write_str(arg0),
+            Self::Float(arg0) => f.write_str(&arg0.to_string()),
+            Self::Int(arg0) => f.write_str(&arg0.to_string()),
+            Self::Bool(arg0) => f.write_str(&arg0.to_string()),
+            Self::Custom(arg0) => f.write_str(&arg0.to_string()),
+        }
+    }
+}
+
 #[cfg(feature = "dioxus")]
 impl<V: FromAnyValue> From<dioxus_core::BorrowedAttributeValue<'_>> for OwnedAttributeValue<V> {
     fn from(value: dioxus_core::BorrowedAttributeValue<'_>) -> Self {
@@ -94,6 +137,7 @@ impl<V: FromAnyValue> From<dioxus_core::BorrowedAttributeValue<'_>> for OwnedAtt
 }
 
 impl<V: FromAnyValue> OwnedAttributeValue<V> {
+    /// Attempt to convert the attribute value to a string.
     pub fn as_text(&self) -> Option<&str> {
         match self {
             OwnedAttributeValue::Text(text) => Some(text),
@@ -101,20 +145,25 @@ impl<V: FromAnyValue> OwnedAttributeValue<V> {
         }
     }
 
+    /// Attempt to convert the attribute value to a float.
     pub fn as_float(&self) -> Option<f64> {
         match self {
             OwnedAttributeValue::Float(float) => Some(*float),
+            OwnedAttributeValue::Int(int) => Some(*int as f64),
             _ => None,
         }
     }
 
+    /// Attempt to convert the attribute value to an integer.
     pub fn as_int(&self) -> Option<i64> {
         match self {
+            OwnedAttributeValue::Float(float) => Some(*float as i64),
             OwnedAttributeValue::Int(int) => Some(*int),
             _ => None,
         }
     }
 
+    /// Attempt to convert the attribute value to a boolean.
     pub fn as_bool(&self) -> Option<bool> {
         match self {
             OwnedAttributeValue::Bool(bool) => Some(*bool),
@@ -122,6 +171,7 @@ impl<V: FromAnyValue> OwnedAttributeValue<V> {
         }
     }
 
+    /// Attempt to convert the attribute value to a custom value.
     pub fn as_custom(&self) -> Option<&V> {
         match self {
             OwnedAttributeValue::Custom(custom) => Some(custom),