Merge pull request #872 from rust-embedded/docs

rm html_escape
rust-embedded · Oct 25, 2024 · 92ff0c7 · 92ff0c7
2 parents 1ee8b00 + aebd7dc
commit 92ff0c7
Show file tree

Hide file tree

Showing 8 changed files with 36 additions and 49 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+- Revert #711
 - Fix calculating `modifiedWriteValues` bitmasks with field arrays
 - Fix building without `yaml` feature
 - Compatibility with `riscv` 0.12 and `riscv-rt` 0.13

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -54,7 +54,6 @@ serde = { version = "1.0", optional = true }
 serde_json = { version = "1.0.85", optional = true }
 serde_yaml = { version = "0.9.11", optional = true }
 regex = "1.10.0"
-html-escape = "0.2"
 url = { version = "2.5", features = ["serde"] }
 
 [dependencies.svd-parser]

diff --git a/src/generate/interrupt.rs b/src/generate/interrupt.rs
@@ -66,7 +66,7 @@ pub fn render(
                 .map(util::respace)
                 .as_deref()
                 .map(util::escape_special_chars)
-                .unwrap_or_else(|| interrupt.0.name.clone())
+                .unwrap_or_else(|| interrupt.0.name.as_str().into())
         );
 
         let value = util::unsuffixed(interrupt.0.value);

diff --git a/src/generate/peripheral.rs b/src/generate/peripheral.rs
@@ -205,8 +205,8 @@ pub fn render(p_original: &Peripheral, index: &Index, config: &Config) -> Result
         }
     }
 
-    let description =
-        util::escape_special_chars(util::respace(p.description.as_ref().unwrap_or(&name)).as_ref());
+    let description = util::respace(p.description.as_ref().unwrap_or(&name));
+    let description = util::escape_special_chars(&description);
 
     // Build up an alternate erc list by expanding any derived registers/clusters
     // erc: *E*ither *R*egister or *C*luster
@@ -511,7 +511,8 @@ impl FieldRegions {
 }
 
 fn make_comment(size: u32, offset: u32, description: &str) -> String {
-    let desc = util::escape_special_chars(&util::respace(description));
+    let desc = util::respace(description);
+    let desc = util::escape_special_chars(&desc);
     if size > 32 {
         let end = offset + size / 8;
         format!("0x{offset:02x}..0x{end:02x} - {desc}")
@@ -1149,7 +1150,7 @@ fn expand_register(
         .properties
         .size
         .ok_or_else(|| anyhow!("Register {} has no `size` field", register.name))?;
-    let description = register.description.clone().unwrap_or_default();
+    let description = register.description.as_deref().unwrap_or_default();
 
     let info_name = register.fullname(config.ignore_groups);
     let mut ty_name = if register.is_single() {
@@ -1161,7 +1162,7 @@ fn expand_register(
 
     match register {
         Register::Single(info) => {
-            let doc = make_comment(register_size, info.address_offset, &description);
+            let doc = make_comment(register_size, info.address_offset, description);
             let span = Span::call_site();
             let ty = name_to_ty(ident(&ty_str, config, "register", span));
             let name: Ident = ident(&ty_name, config, "register_accessor", span);
@@ -1236,7 +1237,7 @@ fn expand_register(
                 let doc = make_comment(
                     register_size * array_info.dim,
                     info.address_offset,
-                    &description,
+                    description,
                 );
                 let mut accessors = Vec::with_capacity((array_info.dim + 1) as _);
                 let first_name = svd::array::names(info, array_info).next().unwrap();
@@ -1380,8 +1381,8 @@ fn cluster_block(
     index: &Index,
     config: &Config,
 ) -> Result<TokenStream> {
-    let description =
-        util::escape_special_chars(&util::respace(c.description.as_ref().unwrap_or(&c.name)));
+    let description = util::respace(c.description.as_ref().unwrap_or(&c.name));
+    let description = util::escape_special_chars(&description);
     let mod_name = c.name.remove_dim().to_string();
 
     // name_snake_case needs to take into account array type.

diff --git a/src/generate/register.rs b/src/generate/register.rs
@@ -65,13 +65,11 @@ pub fn render(
     let reg_ty = ident(&name, config, "register", span);
     let doc_alias = (reg_ty.to_string().as_str() != name).then(|| quote!(#[doc(alias = #name)]));
     let mod_ty = ident(&name, config, "register_mod", span);
-    let description = util::escape_special_chars(
-        util::respace(&register.description.clone().unwrap_or_else(|| {
-            warn!("Missing description for register {}", register.name);
-            Default::default()
-        }))
-        .as_ref(),
-    );
+    let description = util::respace(register.description.as_deref().unwrap_or_else(|| {
+        warn!("Missing description for register {}", register.name);
+        ""
+    }));
+    let description = util::escape_special_chars(&description);
 
     if let Some(dpath) = dpath.as_ref() {
         let mut derived = if &dpath.block == path {
@@ -261,13 +259,11 @@ pub fn render_register_mod(
         rsize.next_power_of_two()
     };
     let rty = rsize.to_ty()?;
-    let description = util::escape_special_chars(
-        util::respace(&register.description.clone().unwrap_or_else(|| {
-            warn!("Missing description for register {rname}");
-            Default::default()
-        }))
-        .as_ref(),
-    );
+    let description = util::respace(&register.description.as_deref().unwrap_or_else(|| {
+        warn!("Missing description for register {rname}");
+        ""
+    }));
+    let description = util::escape_special_chars(&description);
 
     let mut mod_items = TokenStream::new();
 
@@ -898,7 +894,8 @@ pub fn fields(
                                 let pc = &v.pc;
                                 let is_variant = &v.is_sc;
 
-                                let doc = util::escape_special_chars(&util::respace(&v.doc));
+                                let doc = util::respace(&v.doc);
+                                let doc = util::escape_special_chars(&doc);
                                 enum_items.extend(quote! {
                                     #[doc = #doc]
                                     #inline
@@ -911,7 +908,8 @@ pub fn fields(
                                 let pc = &v.pc;
                                 let is_variant = &v.is_sc;
 
-                                let doc = util::escape_special_chars(&util::respace(&v.doc));
+                                let doc = util::respace(&v.doc);
+                                let doc = util::escape_special_chars(&doc);
                                 enum_items.extend(quote! {
                                     #[doc = #doc]
                                     #inline
@@ -1174,7 +1172,8 @@ pub fn fields(
                         for v in &variants {
                             let pc = &v.pc;
                             let sc = &v.sc;
-                            let doc = util::escape_special_chars(&util::respace(&v.doc));
+                            let doc = util::respace(&v.doc);
+                            let doc = util::escape_special_chars(&doc);
                             proxy_items.extend(quote! {
                                 #[doc = #doc]
                                 #inline
@@ -1545,7 +1544,8 @@ fn add_from_variants<'a>(
 
     let mut vars = TokenStream::new();
     for v in variants.map(|v| {
-        let desc = util::escape_special_chars(&util::respace(&format!("{}: {}", v.value, v.doc)));
+        let desc = util::respace(&format!("{}: {}", v.value, v.doc));
+        let desc = util::escape_special_chars(&desc);
         let pcv = &v.pc;
         let pcval = &unsuffixed(v.value);
         quote! {

diff --git a/src/generate/riscv.rs b/src/generate/riscv.rs
@@ -184,7 +184,7 @@ pub fn render(
                     .map(|s| util::respace(s))
                     .as_ref()
                     .map(|s| util::escape_special_chars(s))
-                    .unwrap_or_else(|| i.name.clone())
+                    .unwrap_or_else(|| i.name.as_str().into())
             );
 
             writeln!(device_x, "PROVIDE({name} = DefaultHandler);")?;

diff --git a/src/util.rs b/src/util.rs
@@ -5,7 +5,6 @@ use crate::{
     svd::{Access, Device, Field, RegisterInfo, RegisterProperties},
     Config,
 };
-use html_escape::encode_text_minimal;
 use inflections::Inflect;
 use proc_macro2::{Ident, Span, TokenStream};
 use quote::quote;
@@ -179,9 +178,12 @@ pub fn escape_brackets(s: &str) -> String {
 }
 
 /// Escape basic html tags and brackets
-pub fn escape_special_chars(s: &str) -> String {
-    let html_escaped = encode_text_minimal(s);
-    escape_brackets(&html_escaped)
+pub fn escape_special_chars(s: &str) -> Cow<'_, str> {
+    if s.contains('[') {
+        escape_brackets(&s).into()
+    } else {
+        s.into()
+    }
 }
 
 pub fn name_of<T: FullName>(maybe_array: &MaybeArray<T>, ignore_group: bool) -> String {