Skip to content

Commit

Permalink
Improve docs of Token! macro
Browse files Browse the repository at this point in the history
  • Loading branch information
dtolnay committed Sep 15, 2023
1 parent 319433e commit 6f6b004
Showing 1 changed file with 55 additions and 10 deletions.
65 changes: 55 additions & 10 deletions src/token.rs
Original file line number Diff line number Diff line change
Expand Up @@ -840,25 +840,70 @@ define_delimiters! {
/// A type-macro that expands to the name of the Rust type representation of a
/// given token.
///
/// It can expand to the token type and be used to construct a token from a [`Span`]:
/// As a type, `Token!` is commonly used in the type of struct fields, the type
/// of a `let` statement, or in turbofish for a `parse` function.
///
/// ```
/// # use syn::{Token};
/// use proc_macro2::Span;
/// use syn::{Ident, Token};
/// use syn::parse::{Parse, ParseStream, Result};
///
/// // `struct Foo;`
/// pub struct UnitStruct {
/// struct_token: Token![struct],
/// ident: Ident,
/// semi_token: Token![;],
/// }
///
/// let fn_token: Token![fn] = Token![fn](Span::call_site());
/// impl Parse for UnitStruct {
/// fn parse(input: ParseStream) -> Result<Self> {
/// let struct_token: Token![struct] = input.parse()?;
/// let ident: Ident = input.parse()?;
/// let semi_token = input.parse::<Token![;]>()?;
/// Ok(UnitStruct { struct_token, ident, semi_token })
/// }
/// }
/// ```
/// It can be used with [`ParseBuffer::peek`]:
///
/// As an expression, `Token!` is used for peeking tokens or instantiating
/// tokens from a span.
///
/// ```
/// # use syn::{Token, parse::ParseStream};
/// # fn parser(input: ParseStream) {
/// input.peek(Token![<<]);
/// # use syn::{Ident, Token};
/// # use syn::parse::{Parse, ParseStream, Result};
/// #
/// # struct UnitStruct {
/// # struct_token: Token![struct],
/// # ident: Ident,
/// # semi_token: Token![;],
/// # }
/// #
/// # impl Parse for UnitStruct {
/// # fn parse(input: ParseStream) -> Result<Self> {
/// # unimplemented!()
/// # }
/// # }
/// #
/// fn make_unit_struct(name: Ident) -> UnitStruct {
/// let span = name.span();
/// UnitStruct {
/// struct_token: Token![struct](span),
/// ident: name,
/// semi_token: Token![;](span),
/// }
/// }
///
/// # fn parse(input: ParseStream) -> Result<()> {
/// if input.peek(Token![struct]) {
/// let unit_struct: UnitStruct = input.parse()?;
/// /* ... */
/// }
/// # Ok(())
/// # }
/// ```
///
/// See the [token module] documentation for details and more examples.
/// See the [token module] documentation for details and examples.
///
/// [token module]: crate::token
/// [`ParseBuffer::peek`]: crate::parse::ParseBuffer::peek
#[macro_export]
macro_rules! Token {
[abstract] => { $crate::token::Abstract };
Expand Down

0 comments on commit 6f6b004

Please sign in to comment.