Merge #20

20: move doc comments inside macro invocations r=Disasm a=euclio

[rust-lang/rust#57882](https://github.com/rust-lang/rust/pull/57882) is modifying the `unused_doc_comments` lint to fire on mistakenly documented macro expansions. Note that these doc comments are not currently used, since they are eliminated when the macro is expanded. A crater run detected that this crate will break due to this change, likely because of the use of `deny(unused_doc_comments)` or `deny(warnings)`.

While this kind of breakage is allowed under Rust's stability guarantees, I am opening PRs to affected crates to reduce the impact.

This PR protects your crate from future breakage by moving the offending doc comments inside the macro invocations.

Co-authored-by: Andy Russell <arussell123@gmail.com>

src/register/macros.rs

@@ -183,7 +183,8 @@ macro_rules! clear {
 }
 
 macro_rules! set_csr {
-    ($set_field:ident, $e:expr) => {
+    ($(#[$attr:meta])*, $set_field:ident, $e:expr) => {
+        $(#[$attr])*
         #[inline]
         pub unsafe fn $set_field() {
             _set($e);
@@ -192,7 +193,8 @@ macro_rules! set_csr {
 }
 
 macro_rules! clear_csr {
-    ($clear_field:ident, $e:expr) => {
+    ($(#[$attr:meta])*, $clear_field:ident, $e:expr) => {
+        $(#[$attr])*
         #[inline]
         pub unsafe fn $clear_field() {
             _clear($e);
@@ -201,8 +203,8 @@ macro_rules! clear_csr {
 }
 
 macro_rules! set_clear_csr {
-    ($set_field:ident, $clear_field:ident, $e:expr) => {
-        set_csr!($set_field, $e);
-        clear_csr!($clear_field, $e);
+    ($(#[$attr:meta])*, $set_field:ident, $clear_field:ident, $e:expr) => {
+        set_csr!($(#[$attr])*, $set_field, $e);
+        clear_csr!($(#[$attr])*, $clear_field, $e);
     }
-}
+}

src/register/mie.rs

@@ -72,21 +72,30 @@ read_csr_as!(Mie, 0x304, __read_mie);
 set!(0x304, __set_mie);
 clear!(0x304, __clear_mie);
 
-/// User Software Interrupt Enable
-set_clear_csr!(set_usoft, clear_usoft, 1 << 0);
-/// Supervisor Software Interrupt Enable
-set_clear_csr!(set_ssoft, clear_ssoft, 1 << 1);
-/// Machine Software Interrupt Enable
-set_clear_csr!(set_msoft, clear_msoft, 1 << 3);
-/// User Timer Interrupt Enable
-set_clear_csr!(set_utimer, clear_utimer, 1 << 4);
-/// Supervisor Timer Interrupt Enable
-set_clear_csr!(set_stimer, clear_stimer, 1 << 5);
-/// Machine Timer Interrupt Enable
-set_clear_csr!(set_mtimer, clear_mtimer, 1 << 7);
-/// User External Interrupt Enable
-set_clear_csr!(set_uext, clear_uext, 1 << 8);
-/// Supervisor External Interrupt Enable
-set_clear_csr!(set_sext, clear_sext, 1 << 9);
-/// Machine External Interrupt Enable
-set_clear_csr!(set_mext, clear_mext, 1 << 11);
+set_clear_csr!(
+    /// User Software Interrupt Enable
+    , set_usoft, clear_usoft, 1 << 0);
+set_clear_csr!(
+    /// Supervisor Software Interrupt Enable
+    , set_ssoft, clear_ssoft, 1 << 1);
+set_clear_csr!(
+    /// Machine Software Interrupt Enable
+    , set_msoft, clear_msoft, 1 << 3);
+set_clear_csr!(
+    /// User Timer Interrupt Enable
+    , set_utimer, clear_utimer, 1 << 4);
+set_clear_csr!(
+    /// Supervisor Timer Interrupt Enable
+    , set_stimer, clear_stimer, 1 << 5);
+set_clear_csr!(
+    /// Machine Timer Interrupt Enable
+    , set_mtimer, clear_mtimer, 1 << 7);
+set_clear_csr!(
+    /// User External Interrupt Enable
+    , set_uext, clear_uext, 1 << 8);
+set_clear_csr!(
+    /// Supervisor External Interrupt Enable
+    , set_sext, clear_sext, 1 << 9);
+set_clear_csr!(
+    /// Machine External Interrupt Enable
+    , set_mext, clear_mext, 1 << 11);

src/register/mstatus.rs

@@ -83,18 +83,24 @@ read_csr_as!(Mstatus, 0x300, __read_mstatus);
 set!(0x300, __set_mstatus);
 clear!(0x300, __clear_mstatus);
 
-/// User Interrupt Enable
-set_clear_csr!(set_uie, clear_uie, 1 << 0);
-/// Supervisor Interrupt Enable
-set_clear_csr!(set_sie, clear_sie, 1 << 1);
-/// Machine Interrupt Enable
-set_clear_csr!(set_mie, clear_mie, 1 << 3);
-/// User Previous Interrupt Enable
-set_csr!(set_upie, 1 << 4);
-/// Supervisor Previous Interrupt Enable
-set_csr!(set_spie, 1 << 5);
-/// Machine Previous Interrupt Enable
-set_csr!(set_mpie, 1 << 7);
+set_clear_csr!(
+    /// User Interrupt Enable
+    , set_uie, clear_uie, 1 << 0);
+set_clear_csr!(
+    /// Supervisor Interrupt Enable
+    , set_sie, clear_sie, 1 << 1);
+set_clear_csr!(
+    /// Machine Interrupt Enable
+    , set_mie, clear_mie, 1 << 3);
+set_csr!(
+    /// User Previous Interrupt Enable
+    , set_upie, 1 << 4);
+set_csr!(
+    /// Supervisor Previous Interrupt Enable
+    , set_spie, 1 << 5);
+set_csr!(
+    /// Machine Previous Interrupt Enable
+    , set_mpie, 1 << 7);
 /// Supervisor Previous Privilege Mode
 #[inline]
 pub unsafe fn set_spp(spp: SPP) {

src/register/sie.rs

@@ -56,15 +56,21 @@ read_csr_as!(Sie, 0x104, __read_sie);
 set!(0x104, __set_sie);
 clear!(0x104, __clear_sie);
 
-/// User Software Interrupt Enable
-set_clear_csr!(set_usoft, clear_usoft, 1 << 0);
-/// Supervisor Software Interrupt Enable
-set_clear_csr!(set_ssoft, clear_ssoft, 1 << 1);
-/// User Timer Interrupt Enable
-set_clear_csr!(set_utimer, clear_utimer, 1 << 4);
-/// Supervisor Timer Interrupt Enable
-set_clear_csr!(set_stimer, clear_stimer, 1 << 5);
-/// User External Interrupt Enable
-set_clear_csr!(set_uext, clear_uext, 1 << 8);
-/// Supervisor External Interrupt Enable
-set_clear_csr!(set_sext, clear_sext, 1 << 9);
+set_clear_csr!(
+    /// User Software Interrupt Enable
+    , set_usoft, clear_usoft, 1 << 0);
+set_clear_csr!(
+    /// Supervisor Software Interrupt Enable
+    , set_ssoft, clear_ssoft, 1 << 1);
+set_clear_csr!(
+    /// User Timer Interrupt Enable
+    , set_utimer, clear_utimer, 1 << 4);
+set_clear_csr!(
+    /// Supervisor Timer Interrupt Enable
+    , set_stimer, clear_stimer, 1 << 5);
+set_clear_csr!(
+    /// User External Interrupt Enable
+    , set_uext, clear_uext, 1 << 8);
+set_clear_csr!(
+    /// Supervisor External Interrupt Enable
+    , set_sext, clear_sext, 1 << 9);

src/register/sstatus.rs

@@ -108,18 +108,24 @@ read_csr_as!(Sstatus, 0x100, __read_sstatus);
 set!(0x100, __set_sstatus);
 clear!(0x100, __clear_sstatus);
 
-/// User Interrupt Enable
-set_clear_csr!(set_uie, clear_uie, 1 << 0);
-/// Supervisor Interrupt Enable
-set_clear_csr!(set_sie, clear_sie, 1 << 1);
-/// User Previous Interrupt Enable
-set_csr!(set_upie, 1 << 4);
-/// Supervisor Previous Interrupt Enable
-set_csr!(set_spie, 1 << 5);
-/// Make eXecutable Readable
-set_clear_csr!(set_mxr, clear_mxr, 1 << 19);
-/// Permit Supervisor User Memory access
-set_clear_csr!(set_sum, clear_sum, 1 << 18);
+set_clear_csr!(
+    /// User Interrupt Enable
+    , set_uie, clear_uie, 1 << 0);
+set_clear_csr!(
+    /// Supervisor Interrupt Enable
+    , set_sie, clear_sie, 1 << 1);
+set_csr!(
+    /// User Previous Interrupt Enable
+    , set_upie, 1 << 4);
+set_csr!(
+    /// Supervisor Previous Interrupt Enable
+    , set_spie, 1 << 5);
+set_clear_csr!(
+    /// Make eXecutable Readable
+    , set_mxr, clear_mxr, 1 << 19);
+set_clear_csr!(
+    /// Permit Supervisor User Memory access
+    , set_sum, clear_sum, 1 << 18);
 
 /// Supervisor Previous Privilege Mode
 #[inline]