dtolnay / dtolnay/syn

improve docs for writing attribute procedural macros that parse ItemFn

Open
#616 1 comment 0 reactions 0 assignees View on GitHub
docs
Dominant language
Rust
Stars
3.4k
Forks
374
Avg merge
1d 5h
Merged PRs (30d)
2

Description

The signature of these procedural macros is `fn cool_fn_macro(attr: TokenStream, item: TokenStream) -> TokenStream` and they usually start with `let mut function = parse_macro_input!(item as ItemFn);`. The `attr` argument that the macro receives includes only the inner part of the attribute:
```
#[cool_fn_macro(category = "suite", name = "task_long")]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
attr: TokenStream
```
The way to parse this `attr` is with `parse_macro_input!(attr as Vec)` or equivalently `parse_macro_input!(attr as AttributeArgs)`. But this was hard to discover on my part.

I suggest including this last bit of information in the AttributeArgs, Meta, and any related pages so that future authors will have an easier time than I did. In particular, it would be nice to find the correct type in the [doc index](https://docs.rs/syn/0.15.30/syn/index.html) by searching for similar syntax, similarly to how the short docs for the other types is written out.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.