docs: 补全文档，deny missing docs

feat: use `Str` for every string
Signed-off-by: YdrMaster <[email protected]>

Author: YdrMaster

CHANGELOG.md

@@ -12,13 +12,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## 未发布
 
+## Unreleased
+
 ### Changed
 
 - 规范化更新日志格式
+- 字符串统一使用一个封装的 `Str` 类型（包括节点名、属性名、`<string>` 类型的属性值、路径），类似于 `str` 但未检查是否符合 utf-8 编码
+- 格式化 `Str` 不再自带引号
+- 补全文档并禁止不写文档
 
 ---
 
 - standardize the change log
+- uses an encapsulated `Str` type uniformly for strings (including node name, property name, property value of `<string>`, path), similar to `str` but not checked for utf-8 encoding
+- will not add quotes when formating `Str`
+- completes documentation and missing documentation is denied from now on
 
 ## [0.1.3](https://github.com/YdrMaster/dtb-walker/releases/tag/v0.1.3) - 2022-06-30
 

Cargo.toml

@@ -1,13 +1,12 @@
 [package]
 name = "dtb-walker"
 description = "A simple package for DTB depth-first walking."
-version = "0.1.3"
+version = "0.2.0"
 edition = "2021"
 authors = ["YdrMaster <[email protected]>"]
 repository = "https://github.com/YdrMaster/dtb-walker.git"
+documentation = "https://docs.rs/dtb-walker"
 license = "MIT"
 readme = "README.md"
 keywords = ["device-tree", "dtb"]
 categories = ["no-std"]
-
-[dependencies]

examples/qemu-virt.rs

@@ -22,9 +22,7 @@ fn main() {
     .unwrap();
     dtb.walk(|path, obj| match obj {
         DtbObj::SubNode { name } => {
-            println!("{}{path}/{}", indent(path.level(), INDENT_WIDTH), unsafe {
-                core::str::from_utf8_unchecked(name)
-            });
+            println!("{}{path}/{name}", indent(path.level(), INDENT_WIDTH));
             WalkOperation::StepInto
         }
         DtbObj::Property(prop) => {

src/header.rs

@@ -16,21 +16,60 @@ pub(crate) struct FdtHeader {
     pub size_dt_struct: U32BigEndian,
 }
 
-#[derive(Debug)]
+/// 首部检查可能发现的错误类型。
+#[derive(Clone, PartialEq, Eq, Debug)]
 pub enum HeaderError {
+    /// 设备树整体不对齐。
     Misaligned(u32),
+    /// `magic` 字段不是 0xd00dfeed。
     Magic(u32),
+    /// 版本不兼容。
     Version(u32),
+    /// 最后兼容版本不兼容。
     LastCompVersion(u32),
+    /// 设备树总大小不合理。
     TotalSize(u32),
+    /// 结构块偏移不对齐。
     StructMisaligned(u32),
-    StructOffset { value: u32, expected: Range<u32> },
-    StructSize { value: u32, max: u32 },
+    /// 结构块偏移不合理。
+    StructOffset {
+        /// 解析出的结构块偏移。
+        value: u32,
+        /// 可接受的结构块偏移。
+        expected: Range<u32>,
+    },
+    /// 结构块大小不合理。
+    StructSize {
+        /// 解析出的结构块大小。
+        value: u32,
+        /// 可接受的最大结构块。
+        max: u32,
+    },
+    /// 结构块内容不合理，即没有根节点或不以 END 标记结尾。
     StructContent,
+    /// 地址保护区偏移不对齐。
     MemRsvMisaligned(u32),
-    MemRsvOffset { value: u32, expected: Range<u32> },
-    StringsOffset { value: u32, expected: Range<u32> },
-    StringsSize { value: u32, max: u32 },
+    /// 地址保护区偏移不合理。
+    MemRsvOffset {
+        /// 解析出的地址保护区偏移。
+        value: u32,
+        /// 可接受的地址保护区偏移。
+        expected: Range<u32>,
+    },
+    /// 字符串区偏移不合理。
+    StringsOffset {
+        /// 解析出的字符串区偏移。
+        value: u32,
+        /// 可接受的字符串区偏移。
+        expected: Range<u32>,
+    },
+    /// 字符串区大小不合理。
+    StringsSize {
+        /// 解析出的字符串区大小。
+        value: u32,
+        /// 可接受的字符串区大小。
+        max: u32,
+    },
 }
 
 const FOUR: usize = 4;

src/indent.rs

@@ -5,8 +5,9 @@ pub struct Indent {
     width: usize,
 }
 
+/// 构造一个 `level` 级，每级宽 `width` 的缩进。
 #[inline]
-pub fn indent(level: usize, width: usize) -> Indent {
+pub const fn indent(level: usize, width: usize) -> Indent {
     Indent { level, width }
 }
 

src/lib.rs

@@ -1,5 +1,19 @@
+//! A simple package for DTB depth-first walking.
+//!
+//! # Example
+//!
+//! ```cmd
+//! cargo run --release --example qemu-virt
+//! ```
+//!
+//! # Usage
+//!
+//! ```rust,no_run
+//! Dtb::from_raw_parts(dtb).unwrap()
+//! ```
+
 #![no_std]
-#![deny(warnings)] // cancel this line during developing
+#![deny(warnings, unstable_features, missing_docs)] // cancel this line during developing
 
 mod header;
 mod indent;
@@ -9,8 +23,10 @@ mod structure_block;
 mod walker;
 
 pub use path::Path;
-pub use property::{PHandle, Property, Reg, Str, StrList};
+pub use property::{PHandle, Property, Reg, StrList};
 pub mod utils {
+    //! 用于设备树解析、格式化的工具集。
+
     pub use crate::indent::indent;
 }
 pub use header::HeaderError;
@@ -64,9 +80,12 @@ impl Dtb<'static> {
     }
 }
 
+/// 从内存切片构造设备树二进制对象失败。
 pub enum ConvertError {
-    Truncated,
+    /// 首部检查未通过。
     Header(HeaderError),
+    /// 切片未能容纳整个设备树。
+    Truncated,
 }
 
 impl<'a> Dtb<'a> {
@@ -127,24 +146,61 @@ impl Dtb<'_> {
 
 /// 设备树二进制小对象。
 pub enum DtbObj<'a> {
-    /// 子节点
-    SubNode { name: &'a [u8] },
-    /// 一般属性
+    /// 子节点。
+    SubNode {
+        /// 节点名。
+        name: Str<'a>,
+    },
+    /// 一般属性。
     Property(Property<'a>),
 }
 
 /// 遍历操作。
 pub enum WalkOperation {
-    /// 进入子节点
+    /// 进入子节点。
     StepInto,
-    /// 跳过子节点
+    /// 跳过子节点。
     StepOver,
-    /// 跳过当前子树
+    /// 跳过当前子树。
     StepOut,
-    /// 结束遍历
+    /// 结束遍历。
     Terminate,
 }
 
+/// 地址空间上的一个字符串，但未检查是否符合 utf-8 编码。
+#[derive(Clone, Copy)]
+pub struct Str<'a>(&'a [u8]);
+
+impl Str<'_> {
+    /// Converts to `&[u8]`.
+    #[inline]
+    pub fn as_bytes(&self) -> &[u8] {
+        self.0
+    }
+
+    /// Converts to [`str`].
+    #[inline]
+    pub fn as_str(&self) -> Result<&str, core::str::Utf8Error> {
+        core::str::from_utf8(self.0)
+    }
+
+    /// Converts to [`str`] without checking utf-8 validity.
+    ///
+    /// # Safety
+    ///
+    /// see [`core::str::from_utf8_unchecked`].
+    #[inline]
+    pub unsafe fn as_str_unchecked(&self) -> &str {
+        core::str::from_utf8_unchecked(self.0)
+    }
+}
+
+impl fmt::Display for Str<'_> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        unsafe { self.as_str_unchecked() }.fmt(f)
+    }
+}
+
 #[repr(transparent)]
 #[derive(Clone, Copy, PartialEq, Eq)]
 struct U32BigEndian(u32);

src/path.rs

@@ -1,15 +1,16 @@
-use core::{fmt, str};
+use crate::Str;
+use core::{fmt, str};
 
 /// 设备树节点路径。
 pub struct Path<'a> {
     pub(crate) parent: Option<&'a Path<'a>>,
-    pub(crate) name: &'a [u8],
+    pub(crate) name: Str<'a>,
 }
 
 impl Path<'_> {
     pub(crate) const ROOT: Self = Self {
         parent: None,
-        name: &[],
+        name: Str(&[]),
     };
 
     /// 返回路径层数。定义根节点的子节点层数为 0。
@@ -24,10 +25,16 @@ impl Path<'_> {
 
     /// 返回路径最后一级的节点名。
     #[inline]
-    pub fn last(&self) -> &[u8] {
+    pub fn last(&self) -> Str {
         self.name
     }
 
+    /// 如果这是根节点的路径则返回 `true`。
+    #[inline]
+    pub fn is_root(&self) -> bool {
+        self.name.0.is_empty()
+    }
+
     /// 将路径字符串格式化到 `buf` 中。
     ///
     /// 如果返回 `Ok(n)`，表示字符串长度为 `n`（`n` 不大于 `buf.len()`）。
@@ -42,12 +49,12 @@ impl Path<'_> {
             mut rest => {
                 buf[len] = b'/';
                 rest -= 1;
-                if self.name.len() > rest {
-                    buf[len + 1..].copy_from_slice(&self.name[..rest]);
+                if self.name.0.len() > rest {
+                    buf[len + 1..].copy_from_slice(&self.name.0[..rest]);
                     Err(buf.len())
                 } else {
-                    buf[len + 1..][..self.name.len()].copy_from_slice(self.name);
-                    Ok(len + self.name.len() + 1)
+                    buf[len + 1..][..self.name.0.len()].copy_from_slice(self.name.0);
+                    Ok(len + self.name.0.len() + 1)
                 }
             }
         }
@@ -59,7 +66,7 @@ impl fmt::Display for Path<'_> {
         if let Some(parent) = self.parent {
             parent.fmt(f)?;
             '/'.fmt(f)?;
-            unsafe { str::from_utf8_unchecked(self.name) }.fmt(f)
+            unsafe { str::from_utf8_unchecked(self.name.0) }.fmt(f)
         } else {
             Ok(())
         }

src/property/mod.rs

@@ -4,11 +4,11 @@ mod phandle;
 mod reg;
 mod str;
 
-use crate::StructureBlock;
+use crate::{Str, StructureBlock};
 use core::{fmt, slice};
 
 pub use self::phandle::PHandle;
-pub use self::str::{Str, StrList};
+pub use self::str::StrList;
 pub use reg::Reg;
 pub(crate) use reg::RegCfg;
 
@@ -29,7 +29,12 @@ pub enum Property<'a> {
     /// §2.3.10 DMA 连贯性
     DmaCoherent,
     /// 一般属性
-    General { name: Str<'a>, value: &'a [u8] },
+    General {
+        /// 属性名
+        name: Str<'a>,
+        /// 属性值
+        value: &'a [u8],
+    },
 }
 
 struct Error;

src/property/phandle.rs

@@ -1,8 +1,12 @@
-use core::fmt;
+//! §2.3.3
 
+use core::fmt;
+
+/// §2.3.3 phandle 属性
 pub struct PHandle(pub(super) u32);
 
 impl PHandle {
+    /// 返回 phandle 值。
     #[inline]
     pub fn value(&self) -> u32 {
         self.0