Merge pull request rust-lang-nursery#21 from durka/metadata

support metadata on statics

Author: Kimundi

src/lib.rs

@@ -17,10 +17,13 @@ lazy_static! {
 }
 ```
 
+Metadata (such as doc comments) is allowed on each ref.
+
 # Semantic
 
-For a given `static ref NAME: TYPE = EXPR;`, the macro generates a
-unique type that implements `Deref<TYPE>` and stores it in a static with name `NAME`.
+For a given `static ref NAME: TYPE = EXPR;`, the macro generates a unique type that
+implements `Deref<TYPE>` and stores it in a static with name `NAME`. (Metadata ends up
+attaching to this type.)
 
 On first deref, `EXPR` gets evaluated and stored internally, such that all further derefs
 can return a reference to the same object.
@@ -72,14 +75,14 @@ define uninitialized `static mut` values.
 
 #[macro_export]
 macro_rules! lazy_static {
-    (static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
-        lazy_static!(PRIV static ref $N : $T = $e; $($t)*);
+    ($(#[$attr:meta])* static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
+        lazy_static!(PRIV, $(#[$attr])* static ref $N : $T = $e; $($t)*);
     };
-    (pub static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
-        lazy_static!(PUB static ref $N : $T = $e; $($t)*);
+    ($(#[$attr:meta])* pub static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
+        lazy_static!(PUB, $(#[$attr])* static ref $N : $T = $e; $($t)*);
     };
-    ($VIS:ident static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
-        lazy_static!(MAKE TY $VIS $N);
+    ($VIS:ident, $(#[$attr:meta])* static ref $N:ident : $T:ty = $e:expr; $($t:tt)*) => {
+        lazy_static!(MAKE TY, $VIS, $(#[$attr])*, $N);
         impl ::std::ops::Deref for $N {
             type Target = $T;
             fn deref<'a>(&'a self) -> &'a $T {
@@ -106,18 +109,22 @@ macro_rules! lazy_static {
         }
         lazy_static!($($t)*);
     };
-    (MAKE TY PUB $N:ident) => {
+    (MAKE TY, PUB, $(#[$attr:meta])*, $N:ident) => {
         #[allow(missing_copy_implementations)]
         #[allow(non_camel_case_types)]
         #[allow(dead_code)]
+        $(#[$attr])*
         pub struct $N {__private_field: ()}
+        #[doc(hidden)]
         pub static $N: $N = $N {__private_field: ()};
     };
-    (MAKE TY PRIV $N:ident) => {
+    (MAKE TY, PRIV, $(#[$attr:meta])*, $N:ident) => {
         #[allow(missing_copy_implementations)]
         #[allow(non_camel_case_types)]
         #[allow(dead_code)]
+        $(#[$attr])*
         struct $N {__private_field: ()}
+        #[doc(hidden)]
         static $N: $N = $N {__private_field: ()};
     };
     () => ()

tests/test.rs

@@ -3,20 +3,29 @@ extern crate lazy_static;
 use std::collections::HashMap;
 
 lazy_static! {
-    static ref NUMBER: u32 = times_two(3);
+    /// Documentation!
+    pub static ref NUMBER: u32 = times_two(3);
+
     static ref ARRAY_BOXES: [Box<u32>; 3] = [Box::new(1), Box::new(2), Box::new(3)];
-    static ref STRING: String = "hello".to_string();
+
+    /// More documentation!
+    #[allow(unused_variables)]
+    #[derive(Copy, Clone, Debug)]
+    pub static ref STRING: String = "hello".to_string();
+
     static ref HASHMAP: HashMap<u32, &'static str> = {
         let mut m = HashMap::new();
         m.insert(0, "abc");
         m.insert(1, "def");
         m.insert(2, "ghi");
         m
     };
+
     // This should not compile if the unsafe is removed.
     static ref UNSAFE: u32 = unsafe {
         std::mem::transmute::<i32, u32>(-1)
     };
+
     // This *should* triggger warn(dead_code) by design.
     static ref UNUSED: () = ();
 
@@ -43,6 +52,17 @@ fn test_repeat() {
     assert_eq!(*NUMBER, 6);
 }
 
+#[test]
+fn test_meta() {
+    // this would not compile if STRING were not marked #[derive(Copy, Clone)]
+    let copy_of_string = STRING;
+    // just to make sure it was copied
+    assert!(&STRING as *const _ != &copy_of_string as *const _);
+
+    // this would not compile if STRING were not marked #[derive(Debug)]
+    assert_eq!(format!("{:?}", STRING), "STRING { __private_field: () }".to_string());
+}
+
 mod visibility {
     lazy_static! {
         pub static ref FOO: Box<u32> = Box::new(0);