Skip to content

little cleanups #845

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 3, 2024
Merged

little cleanups #845

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
90ea9f1
little cleanups
burrbull May 29, 2024
e7ee523
readAction warning
burrbull Jun 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

- Use `warning` class in docs
- Refactor `Accessor`

## [v0.33.3] - 2024-05-10
Expand Down
103 changes: 50 additions & 53 deletions src/generate/register.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,21 +109,19 @@ pub fn render(
};

let mut alias_doc = format!(
"{name} ({accs}) register accessor: {description}\n\n{}",
"{name} ({accs}) register accessor: {description}{}{}",
api_docs(
access.can_read(),
access.can_write(),
register.properties.reset_value.is_some(),
&mod_ty,
false,
register.read_action,
)?
)?,
read_action_docs(access.can_read(), register.read_action),
);
if mod_ty != "cfg" {
alias_doc +=
format!("\n\nFor information about available fields see [`mod@{mod_ty}`] module")
.as_str();
}
alias_doc +=
format!("\n\nFor information about available fields see [`mod@{mod_ty}`] module")
.as_str();
let mut out = TokenStream::new();
out.extend(quote! {
#[doc = #alias_doc]
Expand All @@ -149,19 +147,35 @@ pub fn render(
}
}

fn read_action_docs(can_read: bool, read_action: Option<ReadAction>) -> String {
let mut doc = String::new();
if can_read {
if let Some(action) = read_action {
doc.push_str("\n\n<div class=\"warning\">");
doc.push_str(match action {
ReadAction::Clear => "The register is <b>cleared</b> (set to zero) following a read operation.",
ReadAction::Set => "The register is <b>set</b> (set to ones) following a read operation.",
ReadAction::Modify => "The register is <b>modified</b> in some way after a read operation.",
ReadAction::ModifyExternal => "One or more dependent resources other than the current register are immediately affected by a read operation.",
});
doc.push_str("</div>");
}
}
doc
}

fn api_docs(
can_read: bool,
can_write: bool,
can_reset: bool,
module: &Ident,
inmodule: bool,
read_action: Option<ReadAction>,
) -> Result<String, std::fmt::Error> {
fn method(s: &str) -> String {
format!("[`{s}`](crate::generic::Reg::{s})")
format!("[`{s}`](crate::Reg::{s})")
}

let mut doc = String::new();
let mut doc = String::from("\n\n");

if can_read {
write!(
Expand All @@ -170,17 +184,6 @@ fn api_docs(
method("read"),
if inmodule { "(R)" } else { "" },
)?;

if let Some(action) = read_action {
doc.push_str("WARN: ");
doc.push_str(match action {
ReadAction::Clear => "The register is **cleared** (set to zero) following a read operation.",
ReadAction::Set => "The register is **set** (set to ones) following a read operation.",
ReadAction::Modify => "The register is **modified** in some way after a read operation.",
ReadAction::ModifyExternal => "One or more dependent resources other than the current register are immediately affected by a read operation.",
});
}
doc.push(' ');
}

if can_write {
Expand All @@ -203,7 +206,7 @@ fn api_docs(
}

if can_read && can_write {
write!(doc, "You can also {} this register. ", method("modify"),)?;
write!(doc, "You can also {} this register. ", method("modify"))?;
}

doc.push_str("See [API](https://docs.rs/svd2rust/#read--modify--write-api).");
Expand All @@ -220,12 +223,13 @@ pub fn render_register_mod(
) -> Result<TokenStream> {
let properties = &register.properties;
let name = util::name_of(register, config.ignore_groups);
let rname = &register.name;
let span = Span::call_site();
let regspec_ty = regspec(&name, config, span);
let mod_ty = ident(&name, config, "register_mod", span);
let rsize = properties
.size
.ok_or_else(|| anyhow!("Register {} has no `size` field", register.name))?;
.ok_or_else(|| anyhow!("Register {rname} has no `size` field"))?;
let rsize = if rsize < 8 {
8
} else if rsize.is_power_of_two() {
Expand All @@ -236,7 +240,7 @@ pub fn render_register_mod(
let rty = rsize.to_ty()?;
let description = util::escape_special_chars(
util::respace(&register.description.clone().unwrap_or_else(|| {
warn!("Missing description for register {}", register.name);
warn!("Missing description for register {rname}");
Default::default()
}))
.as_ref(),
Expand All @@ -249,15 +253,15 @@ pub fn render_register_mod(
let can_reset = properties.reset_value.is_some();

if can_read {
let desc = format!("Register `{}` reader", register.name);
let desc = format!("Register `{rname}` reader");
mod_items.extend(quote! {
#[doc = #desc]
pub type R = crate::R<#regspec_ty>;
});
}

if can_write {
let desc = format!("Register `{}` writer", register.name);
let desc = format!("Register `{rname}` writer");
mod_items.extend(quote! {
#[doc = #desc]
pub type W = crate::W<#regspec_ty>;
Expand Down Expand Up @@ -356,15 +360,9 @@ pub fn render_register_mod(
}

let doc = format!(
"{description}\n\n{}",
api_docs(
can_read,
can_write,
can_reset,
&mod_ty,
true,
register.read_action,
)?
"{description}{}{}",
api_docs(can_read, can_write, can_reset, &mod_ty, true)?,
read_action_docs(access.can_read(), register.read_action),
);

mod_items.extend(quote! {
Expand Down Expand Up @@ -663,15 +661,11 @@ pub fn fields(
let rv = properties.reset_value.map(|rv| (rv >> offset) & mask);
let fty = width.to_ty()?;

let use_mask;
let use_cast;
if let Some(size) = properties.size {
let (use_cast, use_mask) = if let Some(size) = properties.size {
let size = size.to_ty_width()?;
use_cast = size != width.to_ty_width()?;
use_mask = size != width;
(size != width.to_ty_width()?, size != width)
} else {
use_cast = true;
use_mask = true;
(true, true)
};

let mut lookup_results = Vec::new();
Expand Down Expand Up @@ -724,7 +718,8 @@ pub fn fields(

let brief_suffix = if let Field::Array(_, de) = &f {
if let Some(range) = de.indexes_as_range() {
format!("({}-{})", *range.start(), *range.end())
let (start, end) = range.into_inner();
format!("({start}-{end})")
} else {
let suffixes: Vec<_> = de.indexes().collect();
format!("({})", suffixes.join(","))
Expand Down Expand Up @@ -955,12 +950,14 @@ pub fn fields(
};
let mut readerdoc = field_reader_brief.clone();
if let Some(action) = f.read_action {
readerdoc += match action {
ReadAction::Clear => "\n\nThe field is **cleared** (set to zero) following a read operation.",
ReadAction::Set => "\n\nThe field is **set** (set to ones) following a read operation.",
ReadAction::Modify => "\n\nThe field is **modified** in some way after a read operation.",
ReadAction::ModifyExternal => "\n\nOne or more dependent resources other than the current field are immediately affected by a read operation.",
};
readerdoc.push_str("\n\n<div class=\"warning\">");
readerdoc.push_str(match action {
ReadAction::Clear => "The field is <b>cleared</b> (set to zero) following a read operation.",
ReadAction::Set => "The field is <b>set</b> (set to ones) following a read operation.",
ReadAction::Modify => "The field is <b>modified</b> in some way after a read operation.",
ReadAction::ModifyExternal => "One or more dependent resources other than the current field are immediately affected by a read operation.",
});
readerdoc.push_str("</div>");
}
mod_items.extend(quote! {
#[doc = #readerdoc]
Expand Down Expand Up @@ -996,7 +993,7 @@ pub fn fields(
let increment = de.dim_increment;
let doc = description.expand_dim(&brief_suffix);
let first_name = svd::array::names(f, de).next().unwrap();
let note = format!("NOTE: `n` is number of field in register. `n == 0` corresponds to `{first_name}` field");
let note = format!("<div class=\"warning\">`n` is number of field in register. `n == 0` corresponds to `{first_name}` field.</div>");
let offset_calc = calculate_offset(increment, offset, true);
let value = quote! { ((self.bits >> #offset_calc) & #hexmask) #cast };
let dim = unsuffixed(de.dim);
Expand Down Expand Up @@ -1283,7 +1280,7 @@ pub fn fields(
let offset_calc = calculate_offset(increment, offset, false);
let doc = &description.expand_dim(&brief_suffix);
let first_name = svd::array::names(f, de).next().unwrap();
let note = format!("NOTE: `n` is number of field in register. `n == 0` corresponds to `{first_name}` field");
let note = format!("<div class=\"warning\">`n` is number of field in register. `n == 0` corresponds to `{first_name}` field.</div>");
let dim = unsuffixed(de.dim);
w_impl_items.extend(quote! {
#[doc = #doc]
Expand Down Expand Up @@ -1420,7 +1417,7 @@ impl Variant {
.ok_or_else(|| anyhow!("EnumeratedValue {} has no `<value>` entry", ev.name))?;
Self::from_value(value, ev, config)
})
.collect::<Result<Vec<_>>>()
.collect()
}
fn from_value(value: u64, ev: &EnumeratedValue, config: &Config) -> Result<Self> {
let span = Span::call_site();
Expand Down
20 changes: 5 additions & 15 deletions src/util.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,12 +356,7 @@ impl U32Ext for u32 {
16 => "u16",
32 => "u32",
64 => "u64",
_ => {
return Err(anyhow!(
"can't convert {} bits into register size type",
*self
))
}
_ => return Err(anyhow!("can't convert {self} bits into register size type")),
})
}
fn to_ty(&self) -> Result<Ident> {
Expand All @@ -374,8 +369,7 @@ impl U32Ext for u32 {
33..=64 => "u64",
_ => {
return Err(anyhow!(
"can't convert {} bits into a Rust integral type",
*self
"can't convert {self} bits into a Rust integral type"
))
}
},
Expand All @@ -392,8 +386,7 @@ impl U32Ext for u32 {
33..=64 => 64,
_ => {
return Err(anyhow!(
"can't convert {} bits into a Rust integral type width",
*self
"can't convert {self} bits into a Rust integral type width"
))
}
})
Expand Down Expand Up @@ -437,11 +430,8 @@ pub trait DimSuffix {
impl DimSuffix for str {
fn expand_dim(&self, suffix: &str) -> Cow<str> {
if self.contains("%s") {
if self.contains("[%s]") {
self.replace("[%s]", suffix).into()
} else {
self.replace("%s", suffix).into()
}
self.replace(if self.contains("[%s]") { "[%s]" } else { "%s" }, suffix)
.into()
} else {
self.into()
}
Expand Down
Loading