Improve documentation for the native core and native core macro crates (#528)

* improve documentation for the native core and native core macro crates

* fix spelling of depenency

packages/native-core/src/node_ref.rs

@@ -2,6 +2,7 @@ use dioxus_core::*;
 
 use crate::state::union_ordered_iter;
 
+/// A view into a [VNode] with limited access.
 #[derive(Debug)]
 pub struct NodeView<'a> {
     inner: &'a VNode<'a>,
@@ -9,6 +10,7 @@ pub struct NodeView<'a> {
 }
 
 impl<'a> NodeView<'a> {
+    /// Create a new NodeView from a VNode, and mask.
     pub fn new(mut vnode: &'a VNode<'a>, view: NodeMask, vdom: &'a VirtualDom) -> Self {
         if let VNode::Component(sc) = vnode {
             let scope = vdom.get_scope(sc.scope.get().unwrap()).unwrap();
@@ -20,41 +22,53 @@ impl<'a> NodeView<'a> {
         }
     }
 
+    /// Get the id of the node
     pub fn id(&self) -> ElementId {
         self.inner.mounted_id()
     }
 
+    /// Get the tag of the node if the tag is enabled in the mask
     pub fn tag(&self) -> Option<&'a str> {
-        self.mask.tag.then(|| self.el().map(|el| el.tag)).flatten()
-    }
-
-    pub fn namespace(&self) -> Option<&'a str> {
         self.mask
-            .namespace
-            .then(|| self.el().and_then(|el| el.namespace))
+            .tag
+            .then(|| self.try_element().map(|el| el.tag))
             .flatten()
     }
 
+    /// Get the tag of the node if the namespace is enabled in the mask
+    pub fn namespace(&self) -> Option<&'a str> {
+        self.mask
+            .namespace
+            .then(|| self.try_element().and_then(|el| el.namespace))
+            .flatten()
+    }
+
+    /// Get any attributes that are enabled in the mask
     pub fn attributes(&self) -> impl Iterator<Item = &Attribute<'a>> {
-        self.el()
+        self.try_element()
             .map(|el| el.attributes)
             .unwrap_or_default()
             .iter()
             .filter(|a| self.mask.attritutes.contains_attribute(a.name))
     }
 
+    /// Get the text if it is enabled in the mask
     pub fn text(&self) -> Option<&str> {
         self.mask
             .text
-            .then(|| self.txt().map(|txt| txt.text))
+            .then(|| self.try_text().map(|txt| txt.text))
             .flatten()
     }
 
+    /// Get the listeners if it is enabled in the mask
     pub fn listeners(&self) -> &'a [Listener<'a>] {
-        self.el().map(|el| el.listeners).unwrap_or_default()
+        self.try_element()
+            .map(|el| el.listeners)
+            .unwrap_or_default()
     }
 
-    fn el(&self) -> Option<&'a VElement<'a>> {
+    /// Try to get the underlying element.
+    fn try_element(&self) -> Option<&'a VElement<'a>> {
         if let VNode::Element(el) = &self.inner {
             Some(el)
         } else {
@@ -62,7 +76,8 @@ impl<'a> NodeView<'a> {
         }
     }
 
-    fn txt(&self) -> Option<&'a VText<'a>> {
+    /// Try to get the underlying text node.
+    fn try_text(&self) -> Option<&'a VText<'a>> {
         if let VNode::Text(txt) = &self.inner {
             Some(txt)
         } else {
@@ -71,14 +86,18 @@ impl<'a> NodeView<'a> {
     }
 }
 
+/// A mask that contains a list of attributes that are visible.
 #[derive(PartialEq, Eq, Clone, Debug)]
 pub enum AttributeMask {
     All,
+    /// A list of attribute names that are visible, this list must be sorted
     Dynamic(Vec<&'static str>),
+    /// A list of attribute names that are visible, this list must be sorted
     Static(&'static [&'static str]),
 }
 
 impl AttributeMask {
+    /// A empty attribute mask
     pub const NONE: Self = Self::Static(&[]);
 
     fn contains_attribute(&self, attr: &'static str) -> bool {
@@ -89,10 +108,12 @@ impl AttributeMask {
         }
     }
 
+    /// Create a new dynamic attribute mask with a single attribute
     pub fn single(new: &'static str) -> Self {
         Self::Dynamic(vec![new])
     }
 
+    /// Ensure the attribute list is sorted.
     pub fn verify(&self) {
         match &self {
             AttributeMask::Static(attrs) => debug_assert!(
@@ -107,6 +128,7 @@ impl AttributeMask {
         }
     }
 
+    /// Combine two attribute masks
     pub fn union(&self, other: &Self) -> Self {
         let new = match (self, other) {
             (AttributeMask::Dynamic(s), AttributeMask::Dynamic(o)) => AttributeMask::Dynamic(
@@ -127,6 +149,7 @@ impl AttributeMask {
         new
     }
 
+    /// Check if two attribute masks overlap
     fn overlaps(&self, other: &Self) -> bool {
         fn overlaps_iter(
             self_iter: impl Iterator<Item = &'static str>,
@@ -176,9 +199,9 @@ impl Default for AttributeMask {
     }
 }
 
+/// A mask that limits what parts of a node a dependency can see.
 #[derive(Default, PartialEq, Eq, Clone, Debug)]
 pub struct NodeMask {
-    // must be sorted
     attritutes: AttributeMask,
     tag: bool,
     namespace: bool,
@@ -187,11 +210,14 @@ pub struct NodeMask {
 }
 
 impl NodeMask {
+    /// A node mask with no parts visible.
     pub const NONE: Self = Self::new();
+    /// A node mask with every part visible.
     pub const ALL: Self = Self::new_with_attrs(AttributeMask::All)
         .with_text()
         .with_element();
 
+    /// Check if two masks overlap
     pub fn overlaps(&self, other: &Self) -> bool {
         (self.tag && other.tag)
             || (self.namespace && other.namespace)
@@ -200,6 +226,7 @@ impl NodeMask {
             || (self.listeners && other.listeners)
     }
 
+    /// Combine two node masks
     pub fn union(&self, other: &Self) -> Self {
         Self {
             attritutes: self.attritutes.union(&other.attritutes),
@@ -210,6 +237,7 @@ impl NodeMask {
         }
     }
 
+    /// Create a new node mask with the given attributes
     pub const fn new_with_attrs(attritutes: AttributeMask) -> Self {
         Self {
             attritutes,
@@ -220,29 +248,35 @@ impl NodeMask {
         }
     }
 
+    /// Create a empty node mask
     pub const fn new() -> Self {
         Self::new_with_attrs(AttributeMask::NONE)
     }
 
+    /// Allow the mask to view the tag
     pub const fn with_tag(mut self) -> Self {
         self.tag = true;
         self
     }
 
+    /// Allow the mask to view the namespace
     pub const fn with_namespace(mut self) -> Self {
         self.namespace = true;
         self
     }
 
+    /// Allow the mask to view the namespace and tag
     pub const fn with_element(self) -> Self {
         self.with_namespace().with_tag()
     }
 
+    /// Allow the mask to view the text
     pub const fn with_text(mut self) -> Self {
         self.text = true;
         self
     }
 
+    /// Allow the mask to view the listeners
     pub const fn with_listeners(mut self) -> Self {
         self.listeners = true;
         self