Documentation for top-level parse functions
diff --git a/src/lib.rs b/src/lib.rs
index bdfb51d..b2075a5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -515,13 +515,19 @@
#[doc(hidden)]
pub use error::parse_error;
-/// Parse tokens of source code into the chosen syn data type.
+/// Parse tokens of source code into the chosen syntax tree node.
///
/// This is preferred over parsing a string because tokens are able to preserve
/// information about where in the user's code they were originally written (the
/// "span" of the token), possibly allowing the compiler to produce better error
/// messages.
///
+/// This function parses a `proc_macro::TokenStream` which is the type used for
+/// interop with the compiler in a procedural macro. To parse a
+/// `proc_macro2::TokenStream`, use [`syn::parse2`] instead.
+///
+/// [`syn::parse2`]: fn.parse2.html
+///
/// # Examples
///
/// ```rust
@@ -561,6 +567,16 @@
parse2(tokens.into())
}
+/// Parse a proc-macro2 token stream into the chosen syntax tree node.
+///
+/// This function parses a `proc_macro2::TokenStream` which is commonly useful
+/// when the input comes from a node of the Syn syntax tree, for example the tts
+/// of a [`Macro`] node. When in a procedural macro parsing the
+/// `proc_macro::TokenStream` provided by the compiler, use [`syn::parse`]
+/// instead.
+///
+/// [`Macro`]: struct.Macro.html
+/// [`syn::parse`]: fn.parse.html
#[cfg(feature = "parsing")]
pub fn parse2<T>(tokens: proc_macro2::TokenStream) -> Result<T, ParseError>
where
@@ -587,7 +603,7 @@
}
}
-/// Parse a string of Rust code into the chosen syn data type.
+/// Parse a string of Rust code into the chosen syntax tree node.
///
/// # Examples
///