Various cleanups from github comments

Apply some clarifications and minor code changes based on github review
comments.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

samples/blinky/Cargo.toml

@@ -6,7 +6,7 @@
 name = "rustapp"
 version = "0.1.0"
 edition = "2021"
-description = "A sample hello world application in Rust"
+description = "Blink an LED forever using the GPIO API"
 license = "Apache-2.0 or MIT"
 
 [lib]

samples/blinky/build.rs

@@ -1,3 +1,9 @@
 fn main() {
+    // This call will make make config entries available in the code for every device tree node, to
+    // allow conditional compilation based on whether it is present in the device tree.
+    // For example, it will be possible to have:
+    // ```rust
+    // #[cfg(dt = "aliases::led0")]
+    // ```
     zephyr_build::dt_cfgs();
 }

samples/blinky/sample.yaml

@@ -1,3 +1,4 @@
+# See doc/develop/test/twister.rst for what is here.
 sample:
   name: Blinky Sample
 tests:

zephyr-build/src/devicetree.rs

@@ -30,14 +30,15 @@ mod parse;
 
 pub use augment::{Augment, load_augments};
 
+/// Representation of a parsed device tree.
 pub struct DeviceTree {
     /// The root of the tree.
     root: Rc<Node>,
     /// All of the labels.
     labels: BTreeMap<String, Rc<Node>>,
 }
 
-// This is a single node in the devicetree.
+// A single node in a [`DeviceTree`].
 pub struct Node {
     // The name of the node itself.
     name: String,
@@ -90,27 +91,22 @@ pub enum Word {
 }
 
 impl DeviceTree {
-    /// Decode the zephyr.dts and devicetree_generated.h files from the build and build an internal
+    /// Decode the `zephyr.dts` and `devicetree_generated.h` files from the build and build an internal
     /// representation of the devicetree itself.
     pub fn new<P1: AsRef<Path>, P2: AsRef<Path>>(dts_path: P1, dt_gen: P2) -> DeviceTree {
         let ords = OrdMap::new(dt_gen);
 
         let dts = std::fs::read_to_string(dts_path)
             .expect("Reading zephyr.dts file");
         let dt = parse::parse(&dts, &ords);
-        dt.resolve_phandles();
-        dt.set_parents();
-        dt
-    }
 
-    /// Walk the node tree, fixing any phandles to include their reference.
-    fn resolve_phandles(&self) {
-        self.root.phandle_walk(&self.labels);
-    }
+        // Walk the node tree, fixing any phandles to include their reference.
+        dt.root.phandle_walk(&dt.labels);
 
-    /// Walk the node tree, setting each node's parent appropriately.
-    fn set_parents(&self) {
-        self.root.parent_walk();
+        // Walk the node tree, setting each node's parent appropriately.
+        dt.root.parent_walk();
+
+        dt
     }
 }
 

zephyr-build/src/lib.rs

@@ -84,7 +84,7 @@ pub fn build_kconfig_mod() {
 fn import_dt() -> DeviceTree {
     let zephyr_dts = env::var("ZEPHYR_DTS").expect("ZEPHYR_DTS must be set");
     let gen_include = env::var("BINARY_DIR_INCLUDE_GENERATED")
-        .expect("BINARY_DIR_INCLUDE_GENERATED");
+        .expect("BINARY_DIR_INCLUDE_GENERATED must be set");
 
     let generated = format!("{}/devicetree_generated.h", gen_include);
     DeviceTree::new(&zephyr_dts, generated)