Merge pull request #31 from Manishearth/displaydoc-attr

Add #[displaydoc] attribute

Author: yaahc

CHANGELOG.md

@@ -6,19 +6,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- next-header -->
 
-## [Unreleased] - ReleaseDate
+# [Unreleased] - ReleaseDate
+## Added
+- Added `#[displaydoc("..")]` attribute for overriding a doc comment
 
-## [0.2.2] - 2021-07-01
-# Added
+# [0.2.2] - 2021-07-01
+## Added
 - Added prefix feature to use the doc comment from an enum and prepend it
   before the error message from each variant.
 
-## [0.2.1] - 2021-03-26
-# Added
+# [0.2.1] - 2021-03-26
+## Added
 - Added opt in support for ignoring extra doc attributes
 
-## [0.2.0] - 2021-03-16
-# Changed
+# [0.2.0] - 2021-03-16
+## Changed
 
 - (BREAKING) disallow multiple `doc` attributes in display impl
   [https://github.com/yaahc/displaydoc/pull/22]. Allowing and ignoring extra

Cargo.toml

@@ -15,6 +15,7 @@ A derive macro for implementing the display Trait via a doc comment and string i
 
 [lib]
 proc-macro = true
+path = "src/lib.rs"
 
 [features]
 default = ["std"]

README.md

@@ -18,7 +18,7 @@ displaydoc = "0.2"
 
 <br>
 
-## Example
+### Example
 
 ```rust
 use std::io;
@@ -43,7 +43,7 @@ pub enum DataStoreError {
 
 <br>
 
-## Details
+### Details
 
 - A `Display` impl is generated for your type if you provide doc comment
   messages on the struct or each variant of your enum, as shown above in the
@@ -68,17 +68,20 @@ pub enum DataStoreError {
       “enum: variant”. When added to an enum, the doc comment on the enum
       becomes mandatory. When added to any other type, it has no effect.
 
+- In case you want to have an independent doc comment, the
+  `#[displaydoc("...")` atrribute may be used on the variant or struct to
+  override it.
+
 <br>
 
-## FAQ
+### FAQ
 
 1. **Is this crate `no_std` compatible?**
     * Yes! This crate implements the `core::fmt::Display` trait not the `std::fmt::Display` trait so it should work in `std` and `no_std` environments. Just add `default-features = false`.
 
 2. **Does this crate work with `Path` and `PathBuf` via the `Display` trait?**
     * Yuuup. This crate uses @dtolnay's [autoref specialization technique](https://github.com/dtolnay/case-studies/blob/master/autoref-specialization/README.md) to add a special trait for types to get the display impl, it then specializes for `Path` and `PathBuf` and when either of these types are found it calls `self.display()` to get a `std::path::Display<'_>` type which can be used with the Display format specifier!
 
-<br>
 
 #### License
 

README.tpl

@@ -0,0 +1,23 @@
+derive(Display) /// `From<docs>`
+===============
+
+[![Latest Version](https://img.shields.io/crates/v/displaydoc.svg)](https://crates.io/crates/displaydoc)
+[![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/displaydoc)
+
+{{readme}}
+
+
+#### License
+
+<sup>
+Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
+2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
+</sup>
+
+<br>
+
+<sub>
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
+be dual licensed as above, without any additional terms or conditions.
+</sub>

src/attr.rs

@@ -54,6 +54,21 @@ impl AttrsHelper {
     }
 
     pub(crate) fn display(&self, attrs: &[Attribute]) -> Result<Option<Display>> {
+        let displaydoc_attr = attrs.iter().find(|attr| attr.path.is_ident("displaydoc"));
+
+        if let Some(displaydoc_attr) = displaydoc_attr {
+            let lit = displaydoc_attr
+                .parse_args()
+                .expect("#[displaydoc(\"foo\")] must contain string arguments");
+            let mut display = Display {
+                fmt: lit,
+                args: TokenStream::new(),
+            };
+
+            display.expand_shorthand();
+            return Ok(Some(display));
+        }
+
         let num_doc_attrs = attrs
             .iter()
             .filter(|attr| attr.path.is_ident("doc"))

src/lib.rs

@@ -62,6 +62,10 @@
 //!       “enum: variant”. When added to an enum, the doc comment on the enum
 //!       becomes mandatory. When added to any other type, it has no effect.
 //!
+//! - In case you want to have an independent doc comment, the
+//!   `#[displaydoc("...")` atrribute may be used on the variant or struct to
+//!   override it.
+//!
 //! <br>
 //!
 //! ## FAQ
@@ -108,7 +112,7 @@ use syn::{parse_macro_input, DeriveInput};
 /// Derive macro for implementing `Display` via doc comment attributes
 #[proc_macro_derive(
     Display,
-    attributes(ignore_extra_doc_attributes, prefix_enum_doc_attributes,)
+    attributes(ignore_extra_doc_attributes, prefix_enum_doc_attributes, displaydoc)
 )]
 pub fn derive_error(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);

tests/happy.rs

@@ -38,6 +38,11 @@ enum Happy {
     /// The path {0}
     #[cfg(feature = "std")]
     Variant6(PathBuf),
+
+    /// These docs are ignored
+    #[displaydoc("Variant7 has a parameter {0} and uses #[displaydoc]")]
+    /// These docs are also ignored
+    Variant7(u32),
 }
 
 // Used for testing indented doc comments
@@ -98,7 +103,10 @@ fn does_it_print() {
         Happy::Variant5(2),
         "Variant5 has a parameter 2 and some regular comments",
     );
-
+    assert_display(
+        Happy::Variant7(2),
+        "Variant7 has a parameter 2 and uses #[displaydoc]",
+    );
     assert_display(HappyStruct { thing: "hi" }, "Just a basic struct hi");
 
     assert_display(HappyStruct2 { thing: "hi2" }, "Just a basic struct hi2");