add some documentation.

also some minor touchups

Author: Emilgardis

svd-parser/src/registerproperties.rs

@@ -7,7 +7,7 @@ impl Parse for RegisterProperties {
     type Config = Config;
 
     fn parse(tree: &Node, config: &Self::Config) -> Result<Self, Self::Error> {
-        RegisterProperties::builder()
+        RegisterProperties::new()
             .size(optional::<u32>("size", tree, &())?)
             .access(optional::<Access>("access", tree, config)?)
             .reset_value(optional::<u64>("resetValue", tree, &())?)

svd-rs/src/access.rs

@@ -46,6 +46,7 @@ impl Default for Access {
 }
 
 impl Access {
+    /// Parse a string into an [Access] value, returning [`Option::None`] if the string is not valid.
     pub fn parse_str(s: &str) -> Option<Self> {
         match s {
             "read-only" => Some(Self::ReadOnly),
@@ -57,6 +58,7 @@ impl Access {
         }
     }
 
+    /// Convert this [`Access`] into a static string.
     pub const fn as_str(self) -> &'static str {
         match self {
             Self::ReadOnly => "read-only",

svd-rs/src/addressblock.rs

@@ -1,17 +1,25 @@
+///  An uniquely mapped address block to a peripheral
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[derive(Clone, Debug, PartialEq)]
 pub struct AddressBlock {
+    /// Specifies the start address of an address block relative to the peripheral [`baseAddress`](crate::Peripheral::base_address).
     pub offset: u32,
+    /// Specifies the number of [`addressUnitBits`](crate::Device::address_unit_bits) being covered by this address block.
     pub size: u32,
+    /// Usage of the address block.
     pub usage: AddressBlockUsage,
 }
 
+/// Usage of the address block.
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "kebab-case"))]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum AddressBlockUsage {
+    /// Registers
     Registers,
+    /// Buffer / Memory
     Buffer,
+    /// Reserved
     Reserved,
 }
 
@@ -22,6 +30,7 @@ impl Default for AddressBlockUsage {
 }
 
 impl AddressBlockUsage {
+    /// Parse a string into an [AddressBlockUsage] value, returning [`Option::None`] if the string is not valid.
     pub fn parse_str(s: &str) -> Option<Self> {
         match s {
             "registers" => Some(Self::Registers),
@@ -31,6 +40,7 @@ impl AddressBlockUsage {
         }
     }
 
+    /// Convert this [`AddressBlockUsage`] into a static string.
     pub const fn as_str(self) -> &'static str {
         match self {
             Self::Registers => "registers",

svd-rs/src/bitrange.rs

@@ -1,9 +1,12 @@
+/// Errors for bit ranges
 #[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
 pub enum Error {
+    /// The bit range is 0 bits wide
     #[error("bitRange width of 0 does not make sense")]
     ZeroWidth,
 }
 
+/// A bit range, describing the [least significant bit](Self::lsb) and [most significant bit](Self::msb)
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct BitRange {
     /// Value defining the position of the least significant bit of the field within the register
@@ -12,40 +15,52 @@ pub struct BitRange {
     /// Value defining the bit-width of the bitfield within the register
     pub width: u32,
 
+    /// The underlying description of the bit range
     pub range_type: BitRangeType,
 }
 
+/// The style of bit range that describes a [BitRange]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum BitRangeType {
+    /// A bit range in the format: `[<msb>:<lsb>]`
     BitRange,
+    /// A bit range described as offset and width
     OffsetWidth,
+    /// A bit range described as lsb and msb as separate elements
     MsbLsb,
 }
 
 impl BitRange {
+    /// Get the position of the least significant bit
     pub fn lsb(&self) -> u32 {
         self.offset
     }
+    /// Get the position of the most significant bit
     pub fn msb(&self) -> u32 {
         self.offset + self.width - 1
     }
+    /// Get the bit range in the format `[<msb>:<lsb>]`
     pub fn bit_range(&self) -> String {
         format!("[{}:{}]", self.msb(), self.lsb())
     }
+    /// Construct a [`BitRange`] from a offset and width
     pub fn from_offset_width(offset: u32, width: u32) -> Self {
         Self {
             offset,
             width,
             range_type: BitRangeType::OffsetWidth,
         }
     }
+
+    /// Construct a [`BitRange`] from a msb and lsb
     pub fn from_msb_lsb(msb: u32, lsb: u32) -> Self {
         Self {
             offset: lsb,
             width: msb - lsb + 1,
             range_type: BitRangeType::MsbLsb,
         }
     }
+    /// Construct a [`BitRange`] from string in the format `[<msb>:<lsb>]`
     pub fn from_bit_range(text: &str) -> Option<Self> {
         if !text.starts_with('[') || !text.ends_with(']') {
             return None;

svd-rs/src/cluster.rs

@@ -2,9 +2,12 @@ use core::ops::{Deref, DerefMut};
 
 use super::{ClusterInfo, DimElement};
 
+/// Cluster describes a sequence of neighboring registers within a peripheral.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Cluster {
+    /// A single cluster, without any dimension.
     Single(ClusterInfo),
+    /// A cluster array
     Array(ClusterInfo, DimElement),
 }
 

svd-rs/src/clusterinfo.rs

@@ -3,12 +3,15 @@ use super::{
     BuildError, EmptyToNone, RegisterCluster, RegisterProperties, SvdError, ValidateLevel,
 };
 
+/// Errors from [`ClusterInfo::validate`]
 #[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
 pub enum Error {
+    /// The cluster is can not be empty
     #[error("Cluster must contain at least one Register or Cluster")]
     EmptyCluster,
 }
 
+/// Description of a cluster
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
 #[derive(Clone, Debug, PartialEq)]
@@ -40,6 +43,7 @@ pub struct ClusterInfo {
     #[cfg_attr(feature = "serde", serde(flatten))]
     pub default_register_properties: RegisterProperties,
 
+    /// Children/members of the cluster
     pub children: Vec<RegisterCluster>,
 
     /// Specify the cluster name from which to inherit data.
@@ -51,6 +55,7 @@ pub struct ClusterInfo {
     pub derived_from: Option<String>,
 }
 
+/// Builder for [`ClusterInfo`]
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct ClusterInfoBuilder {
     name: Option<String>,
@@ -77,34 +82,42 @@ impl From<ClusterInfo> for ClusterInfoBuilder {
 }
 
 impl ClusterInfoBuilder {
+    /// Set the name of the cluster.
     pub fn name(mut self, value: String) -> Self {
         self.name = Some(value);
         self
     }
+    /// Set the description of the cluster.
     pub fn description(mut self, value: Option<String>) -> Self {
         self.description = value;
         self
     }
+    /// Set the struct type name of the cluster. If not specified, the name of the cluster should be used.
     pub fn header_struct_name(mut self, value: Option<String>) -> Self {
         self.header_struct_name = value;
         self
     }
+    /// Set the address_offset of the cluster, relative to the [`baseAddress`](crate::Peripheral::base_address) of the peripheral.
     pub fn address_offset(mut self, value: u32) -> Self {
         self.address_offset = Some(value);
         self
     }
+    /// Set the default_register_properties of the cluster.
     pub fn default_register_properties(mut self, value: RegisterProperties) -> Self {
         self.default_register_properties = value;
         self
     }
+    /// Set the children of the cluster.
     pub fn children(mut self, value: Vec<RegisterCluster>) -> Self {
         self.children = Some(value);
         self
     }
+    /// Set the derived_from of the cluster.
     pub fn derived_from(mut self, value: Option<String>) -> Self {
         self.derived_from = value;
         self
     }
+    /// Validate and build a [`ClusterInfo`].
     pub fn build(self, lvl: ValidateLevel) -> Result<ClusterInfo, SvdError> {
         let mut cluster = ClusterInfo {
             name: self
@@ -129,10 +142,12 @@ impl ClusterInfoBuilder {
 }
 
 impl ClusterInfo {
+    /// Make a builder for [`ClusterInfo`]
     pub fn builder() -> ClusterInfoBuilder {
         ClusterInfoBuilder::default()
     }
 
+    /// Modify an existing [`ClusterInfo`] based on a [builder](ClusterInfoBuilder).
     pub fn modify_from(
         &mut self,
         builder: ClusterInfoBuilder,
@@ -168,6 +183,7 @@ impl ClusterInfo {
         }
     }
 
+    /// Validate the [`ClusterInfo`]
     pub fn validate(&mut self, lvl: ValidateLevel) -> Result<(), SvdError> {
         if lvl.is_strict() {
             super::check_dimable_name(&self.name, "name")?;
@@ -184,7 +200,7 @@ impl ClusterInfo {
 }
 
 impl ClusterInfo {
-    /// returns iterator over all registers cluster contains
+    /// returns a iterator over all registers the cluster contains
     pub fn reg_iter(&self) -> RegIter {
         let mut rem: Vec<&RegisterCluster> = Vec::with_capacity(self.children.len());
         for r in self.children.iter().rev() {
@@ -193,7 +209,7 @@ impl ClusterInfo {
         RegIter { rem }
     }
 
-    /// returns mutable iterator over all registers cluster contains
+    /// returns a mutable iterator over all registers cluster contains
     pub fn reg_iter_mut(&mut self) -> RegIterMut {
         let mut rem: Vec<&mut RegisterCluster> = Vec::with_capacity(self.children.len());
         for r in self.children.iter_mut().rev() {

svd-rs/src/cpu.rs

@@ -1,10 +1,11 @@
 use super::{BuildError, Endian, SvdError, ValidateLevel};
-
+/// CPU describes the processor included in the microcontroller device.
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
 #[derive(Clone, Debug, PartialEq)]
 #[non_exhaustive]
 pub struct Cpu {
+    /// Processor architecture
     pub name: String,
 
     /// Define the HW revision of the processor
@@ -26,6 +27,7 @@ pub struct Cpu {
     pub has_vendor_systick: bool,
 }
 
+/// Builder for [`Cpu`]
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct CpuBuilder {
     name: Option<String>,
@@ -52,34 +54,42 @@ impl From<Cpu> for CpuBuilder {
 }
 
 impl CpuBuilder {
+    /// Set the name of the cpu.
     pub fn name(mut self, value: String) -> Self {
         self.name = Some(value);
         self
     }
+    /// Set the revision of the cpu.
     pub fn revision(mut self, value: String) -> Self {
         self.revision = Some(value);
         self
     }
+    /// Set the endian of the cpu.
     pub fn endian(mut self, value: Endian) -> Self {
         self.endian = Some(value);
         self
     }
+    /// Set the mpu_present of the cpu.
     pub fn mpu_present(mut self, value: bool) -> Self {
         self.mpu_present = Some(value);
         self
     }
+    /// Set the fpu_present of the cpu.
     pub fn fpu_present(mut self, value: bool) -> Self {
         self.fpu_present = Some(value);
         self
     }
+    /// Set the nvic_priority_bits of the cpu.
     pub fn nvic_priority_bits(mut self, value: u32) -> Self {
         self.nvic_priority_bits = Some(value);
         self
     }
+    /// Set the has_vendor_systick of the cpu.
     pub fn has_vendor_systick(mut self, value: bool) -> Self {
         self.has_vendor_systick = Some(value);
         self
     }
+    /// Validate and build a [`Cpu`].
     pub fn build(self, lvl: ValidateLevel) -> Result<Cpu, SvdError> {
         let mut cpu = Cpu {
             name: self
@@ -112,9 +122,11 @@ impl CpuBuilder {
 }
 
 impl Cpu {
+    /// Make a builder for [`Cpu`]
     pub fn builder() -> CpuBuilder {
         CpuBuilder::default()
     }
+    /// Modify an existing [`Cpu`] based on a [builder](CpuBuilder).
     pub fn modify_from(&mut self, builder: CpuBuilder, lvl: ValidateLevel) -> Result<(), SvdError> {
         if let Some(name) = builder.name {
             self.name = name;
@@ -143,10 +155,12 @@ impl Cpu {
             Ok(())
         }
     }
+    /// Validate the [`Cpu`]
     pub fn validate(&mut self, _lvl: ValidateLevel) -> Result<(), SvdError> {
         // TODO
         Ok(())
     }
+    /// Check if the [`Cpu`] is a Cortex-M
     pub fn is_cortex_m(&self) -> bool {
         self.name.starts_with("CM")
     }

svd-rs/src/derive_from.rs

@@ -1,3 +1,4 @@
+//! Implementations of DeriveFrom, setting non-explicit fields.
 use crate::{
     ClusterInfo, EnumeratedValues, FieldInfo, Peripheral, RegisterInfo, RegisterProperties,
 };