Skip to content

Commit 41915ee

Browse files
tgross35tgross35
authored
Merge pull request #3802 from rust-lang/tgross35-macros-cleanup
Update macro docs and formatting
2 parents e209061 + d5019f0 commit 41915ee

File tree

1 file changed

+103
-60
lines changed

1 file changed

+103
-60
lines changed

‎src/macros.rs‎

Lines changed: 103 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -61,13 +61,23 @@ macro_rules! cfg_if {
6161
};
6262
}
6363

64+
/// Implement `Clone` and `Copy` for a struct, as well as `Debug`, `Eq`, `Hash`, and
65+
/// `PartialEq` if the `extra_traits` feature is enabled.
66+
///
67+
/// Use [`s_no_extra_traits`] for structs where the `extra_traits` feature does not
68+
/// make sense, and for unions.
6469
macro_rules! s {
65-
($($(#[$attr:meta])* pub $t:ident $i:ident { $($field:tt)* })*) => ($(
70+
($(
71+
$(#[$attr:meta])*
72+
pub $t:ident $i:ident { $($field:tt)* }
73+
)*) => ($(
6674
s!(it: $(#[$attr])* pub $t $i { $($field)* });
6775
)*);
76+
6877
(it: $(#[$attr:meta])* pub union $i:ident { $($field:tt)* }) => (
6978
compile_error!("unions cannot derive extra traits, use s_no_extra_traits instead");
7079
);
80+
7181
(it: $(#[$attr:meta])* pub struct $i:ident { $($field:tt)* }) => (
7282
__item! {
7383
#[repr(C)]
@@ -85,10 +95,38 @@ macro_rules! s {
8595
);
8696
}
8797

98+
/// Implement `Clone` and `Copy` for a tuple struct, as well as `Debug`, `Eq`, `Hash`,
99+
/// and `PartialEq` if the `extra_traits` feature is enabled.
100+
///
101+
/// This is the same as [`s`] but works for tuple structs.
102+
macro_rules! s_paren {
103+
($(
104+
$(#[$attr:meta])*
105+
pub struct $i:ident ( $($field:tt)* );
106+
)*) => ($(
107+
__item! {
108+
#[cfg_attr(feature = "extra_traits", derive(Debug, Eq, Hash, PartialEq))]
109+
$(#[$attr])*
110+
pub struct $i ( $($field)* );
111+
}
112+
impl ::Copy for $i {}
113+
impl ::Clone for $i {
114+
fn clone(&self) -> $i { *self }
115+
}
116+
)*);
117+
}
118+
119+
/// Implement `Clone` and `Copy` for a struct with no `extra_traits` feature.
120+
///
121+
/// Most items will prefer to use [`s`].
88122
macro_rules! s_no_extra_traits {
89-
($($(#[$attr:meta])* pub $t:ident $i:ident { $($field:tt)* })*) => ($(
123+
($(
124+
$(#[$attr:meta])*
125+
pub $t:ident $i:ident { $($field:tt)* }
126+
)*) => ($(
90127
s_no_extra_traits!(it: $(#[$attr])* pub $t $i { $($field)* });
91128
)*);
129+
92130
(it: $(#[$attr:meta])* pub union $i:ident { $($field:tt)* }) => (
93131
__item! {
94132
#[repr(C)]
@@ -101,6 +139,7 @@ macro_rules! s_no_extra_traits {
101139
fn clone(&self) -> $i { *self }
102140
}
103141
);
142+
104143
(it: $(#[$attr:meta])* pub struct $i:ident { $($field:tt)* }) => (
105144
__item! {
106145
#[repr(C)]
@@ -116,14 +155,26 @@ macro_rules! s_no_extra_traits {
116155
);
117156
}
118157

158+
/// Specify that an enum should have no traits that aren't specified in the macro
159+
/// invocation, i.e. no `Clone` or `Copy`.
119160
macro_rules! missing {
120-
($($(#[$attr:meta])* pub enum $i:ident {})*) => ($(
121-
$(#[$attr])* #[allow(missing_copy_implementations)] pub enum $i { }
161+
($(
162+
$(#[$attr:meta])*
163+
pub enum $i:ident {}
164+
)*) => ($(
165+
$(#[$attr])*
166+
#[allow(missing_copy_implementations)]
167+
pub enum $i { }
122168
)*);
123169
}
124170

171+
/// Implement `Clone` and `Copy` for an enum, as well as `Debug`, `Eq`, `Hash`, and
172+
/// `PartialEq` if the `extra_traits` feature is enabled.
125173
macro_rules! e {
126-
($($(#[$attr:meta])* pub enum $i:ident { $($field:tt)* })*) => ($(
174+
($(
175+
$(#[$attr:meta])*
176+
pub enum $i:ident { $($field:tt)* }
177+
)*) => ($(
127178
__item! {
128179
#[cfg_attr(feature = "extra_traits", derive(Debug, Eq, Hash, PartialEq))]
129180
$(#[$attr])*
@@ -136,89 +187,80 @@ macro_rules! e {
136187
)*);
137188
}
138189

139-
macro_rules! s_paren {
140-
($($(#[$attr:meta])* pub struct $i:ident ( $($field:tt)* ); )* ) => ($(
141-
__item! {
142-
#[cfg_attr(feature = "extra_traits", derive(Debug, Eq, Hash, PartialEq))]
143-
$(#[$attr])*
144-
pub struct $i ( $($field)* );
145-
}
146-
impl ::Copy for $i {}
147-
impl ::Clone for $i {
148-
fn clone(&self) -> $i { *self }
149-
}
150-
)*);
151-
}
152-
153190
cfg_if! {
154191
if #[cfg(feature = "const-extern-fn")] {
192+
/// Define an `unsafe` function that is const as long as `const-extern-fn` is enabled.
155193
macro_rules! f {
156-
($($(#[$attr:meta])* pub $({$constness:ident})* fn $i:ident(
157-
$($arg:ident: $argty:ty),*
158-
) -> $ret:ty {
159-
$($body:stmt);*
160-
})*) => ($(
194+
($(
195+
$(#[$attr:meta])*
196+
pub $({$constness:ident})* fn $i:ident($($arg:ident: $argty:ty),*) -> $ret:ty {
197+
$($body:stmt);*
198+
}
199+
)*) => ($(
161200
#[inline]
162201
$(#[$attr])*
163-
pub $($constness)* unsafe extern fn $i($($arg: $argty),*
164-
) -> $ret {
202+
pub $($constness)* unsafe extern fn $i($($arg: $argty),*) -> $ret {
165203
$($body);*
166204
}
167205
)*)
168206
}
169207

208+
/// Define a safe function that is const as long as `const-extern-fn` is enabled.
170209
macro_rules! safe_f {
171-
($($(#[$attr:meta])* pub $({$constness:ident})* fn $i:ident(
172-
$($arg:ident: $argty:ty),*
173-
) -> $ret:ty {
174-
$($body:stmt);*
175-
})*) => ($(
210+
($(
211+
$(#[$attr:meta])*
212+
pub $({$constness:ident})* fn $i:ident($($arg:ident: $argty:ty),*) -> $ret:ty {
213+
$($body:stmt);*
214+
}
215+
)*) => ($(
176216
#[inline]
177217
$(#[$attr])*
178-
pub $($constness)* extern fn $i($($arg: $argty),*
179-
) -> $ret {
218+
pub $($constness)* extern fn $i($($arg: $argty),*) -> $ret {
180219
$($body);*
181220
}
182221
)*)
183222
}
184223

224+
/// A nonpublic function that is const as long as `const-extern-fn` is enabled.
185225
macro_rules! const_fn {
186-
($($(#[$attr:meta])* $({$constness:ident})* fn $i:ident(
187-
$($arg:ident: $argty:ty),*
188-
) -> $ret:ty {
189-
$($body:stmt);*
190-
})*) => ($(
226+
($(
227+
$(#[$attr:meta])*
228+
$({$constness:ident})* fn $i:ident($($arg:ident: $argty:ty),*) -> $ret:ty {
229+
$($body:stmt);*
230+
}
231+
)*) => ($(
191232
#[inline]
192233
$(#[$attr])*
193-
$($constness)* fn $i($($arg: $argty),*
194-
) -> $ret {
234+
$($constness)* fn $i($($arg: $argty),*) -> $ret {
195235
$($body);*
196236
}
197237
)*)
198238
}
199-
200239
} else {
240+
/// Define an `unsafe` function that is const as long as `const-extern-fn` is enabled.
201241
macro_rules! f {
202-
($($(#[$attr:meta])* pub $({$constness:ident})* fn $i:ident(
203-
$($arg:ident: $argty:ty),*
204-
) -> $ret:ty {
205-
$($body:stmt);*
206-
})*) => ($(
242+
($(
243+
$(#[$attr:meta])*
244+
pub $({$constness:ident})* fn $i:ident($($arg:ident: $argty:ty),*) -> $ret:ty {
245+
$($body:stmt);*
246+
}
247+
)*) => ($(
207248
#[inline]
208249
$(#[$attr])*
209-
pub unsafe extern fn $i($($arg: $argty),*
210-
) -> $ret {
250+
pub unsafe extern fn $i($($arg: $argty),*) -> $ret {
211251
$($body);*
212252
}
213253
)*)
214254
}
215255

256+
/// Define a safe function that is const as long as `const-extern-fn` is enabled.
216257
macro_rules! safe_f {
217-
($($(#[$attr:meta])* pub $({$constness:ident})* fn $i:ident(
218-
$($arg:ident: $argty:ty),*
219-
) -> $ret:ty {
220-
$($body:stmt);*
221-
})*) => ($(
258+
($(
259+
$(#[$attr:meta])*
260+
pub $({$constness:ident})* fn $i:ident($($arg:ident: $argty:ty),*) -> $ret:ty {
261+
$($body:stmt);*
262+
}
263+
)*) => ($(
222264
#[inline]
223265
$(#[$attr])*
224266
pub extern fn $i($($arg: $argty),*
@@ -228,16 +270,17 @@ cfg_if! {
228270
)*)
229271
}
230272

273+
/// A nonpublic function that is const as long as `const-extern-fn` is enabled.
231274
macro_rules! const_fn {
232-
($($(#[$attr:meta])* $({$constness:ident})* fn $i:ident(
233-
$($arg:ident: $argty:ty),*
234-
) -> $ret:ty {
235-
$($body:stmt);*
236-
})*) => ($(
275+
($(
276+
$(#[$attr:meta])*
277+
$({$constness:ident})* fn $i:ident($($arg:ident: $argty:ty),*) -> $ret:ty {
278+
$($body:stmt);*
279+
}
280+
)*) => ($(
237281
#[inline]
238282
$(#[$attr])*
239-
fn $i($($arg: $argty),*
240-
) -> $ret {
283+
fn $i($($arg: $argty),*) -> $ret {
241284
$($body);*
242285
}
243286
)*)

0 commit comments

Comments
 (0)