Encourage format_ident over Ident::new()

2 files changed, 24 insertions, 20 deletions

diff --git a/README.md b/README.md
index 255dc88..7c7f743 100644
--- a/README.md
+++ b/README.md
@@ -148,22 +148,24 @@ quote! {
 }
 ```
 
-The solution is to perform token-level manipulations using the APIs provided by
-Syn and proc-macro2.
+The solution is to build a new identifier token with the correct value. As this
+is such a common case, the `format_ident!` macro provides a convenient utility
+for doing so correctly.
 
 ```rust
-let concatenated = format!("_{}", ident);
-let varname = syn::Ident::new(&concatenated, ident.span());
+let varname = format_ident!("_{}", ident);
 quote! {
     let mut #varname = 0;
 }
 ```
 
-For identifier concatenation specifically, since this is such a common case,
-the `format_ident!` macro provides a more concise equivalent of the above.
+Alternatively, the APIs provided by Syn and proc-macro2 can be used to directly
+build the identifier. This is roughly equivalent to the above, but will not
+handle `ident` being a raw identifier.
 
 ```rust
-let varname = format_ident!("_{}", ident);
+let concatenated = format!("_{}", ident);
+let varname = syn::Ident::new(&concatenated, ident.span());
 quote! {
     let mut #varname = 0;
 }
diff --git a/src/lib.rs b/src/lib.rs
index 18c06df..e9749ec 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -265,33 +265,35 @@ pub mod spanned;
 /// # ;
 /// ```
 ///
-/// The solution is to perform token-level manipulations using the APIs provided
-/// by Syn and proc-macro2.
+/// The solution is to build a new identifier token with the correct value. As
+/// this is such a common case, the [`format_ident!`] macro provides a
+/// convenient utility for doing so correctly.
 ///
 /// ```
-/// # use proc_macro2::{self as syn, Span};
-/// # use quote::quote;
+/// # use proc_macro2::{Ident, Span};
+/// # use quote::{format_ident, quote};
 /// #
-/// # let ident = syn::Ident::new("i", Span::call_site());
+/// # let ident = Ident::new("i", Span::call_site());
 /// #
-/// let concatenated = format!("_{}", ident);
-/// let varname = syn::Ident::new(&concatenated, ident.span());
+/// let varname = format_ident!("_{}", ident);
 /// quote! {
 ///     let mut #varname = 0;
 /// }
 /// # ;
 /// ```
 ///
-/// For identifier concatenation specifically, since this is such a common case,
-/// the [`format_ident!`] macro provides a more concise equivalent of the above.
+/// Alternatively, the APIs provided by Syn and proc-macro2 can be used to
+/// directly build the identifier. This is roughly equivalent to the above, but
+/// will not handle `ident` being a raw identifier.
 ///
 /// ```
-/// # use proc_macro2::{Ident, Span};
-/// # use quote::{format_ident, quote};
+/// # use proc_macro2::{self as syn, Span};
+/// # use quote::quote;
 /// #
-/// # let ident = Ident::new("i", Span::call_site());
+/// # let ident = syn::Ident::new("i", Span::call_site());
 /// #
-/// let varname = format_ident!("_{}", ident);
+/// let concatenated = format!("_{}", ident);
+/// let varname = syn::Ident::new(&concatenated, ident.span());
 /// quote! {
 ///     let mut #varname = 0;
 /// }