Merge pull request #128 from mystor/format_ident_examples

Encourage format_ident! over Ident::new in docs

1 files changed, 15 insertions, 13 deletions

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;
 /// }