Add Documentation for Custom Attributes and Error Reporting in Procedural Macros #39845

JDemler · 2017-02-15T12:03:13Z

This fixes #39821 .

I'm not sure if the process of how to access custom attributes should be documented as well.
But I feel, that this should rather be documented in syn

rust-highfive · 2017-02-15T12:03:22Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

steveklabnik

I have some small formatting comments, but looks good to me!

steveklabnik · 2017-02-15T18:27:33Z

src/doc/book/src/procedural-macros.md

@@ -209,5 +209,73 @@ Ok so now, let's compile `hello-world`. Executing `cargo run` now yields:
 Hello, World! My name is FrenchToast
 Hello, World! My name is Waffles
 ```
+## Custom Attributes
+In some cases it might make sense to allow users some kind of configuration.


could you put a newline above this line, please?

steveklabnik · 2017-02-15T18:28:02Z

src/doc/book/src/procedural-macros.md

+
+
+## Raising Errors
+Let's assume that we do not want to accept `Enums` as input to our custom derive method.


can you add a newline above this line?

steveklabnik · 2017-02-15T18:28:09Z

src/doc/book/src/procedural-macros.md

+```
+
+Multiple attributes can be specified that way.
+


could you delete one of these newlines?

Do you mean the newline before the heading or after the code block?

there should only be one newline, like this:

Multiple attributes can be specified that way. ## Raising Errors

(that is, before the heading)

So the fixed whitespace issues-commit fixed this issue, correct?

xen0n

Some minor nits, but the snippets are LGTM.

xen0n · 2017-02-17T07:30:44Z

src/doc/book/src/procedural-macros.md

+Let's assume that we do not want to accept `Enums` as input to our custom derive method.
+
+This condition can be easily checked with the help of `syn`. 
+But how to we tell the user, that we do not accept `Enums`. 


how to -> how do

trailing . -> ?

xen0n · 2017-02-17T07:31:01Z

src/doc/book/src/procedural-macros.md

+
+This condition can be easily checked with the help of `syn`. 
+But how to we tell the user, that we do not accept `Enums`. 
+The idiomatic was to report errors in procedural macros is to panic:


was -> way

xen0n · 2017-02-17T07:33:40Z

src/doc/book/src/procedural-macros.md

+error: The attribute `HelloWorldName` is currently unknown to the compiler and may have meaning added to it in the future (see issue #29642)
+```
+
+The compiler needs to know that we handle this attribute and to not respond with an error.


we handle -> we're handling

xen0n · 2017-02-17T07:35:19Z

src/doc/book/src/procedural-macros.md

@@ -210,4 +210,74 @@ Hello, World! My name is FrenchToast
 Hello, World! My name is Waffles
 ```

-We've done it!


Removing this for the next section seems to make the previous section truncated, IMO removal is not needed.

xen0n · 2017-02-17T07:36:31Z

src/doc/book/src/procedural-macros.md

+## Custom Attributes
+
+In some cases it might make sense to allow users some kind of configuration.
+For our example the user might want to overwrite the name that is printed in the `hello_world()` method.


For example, ... is enough for introducing the example.

xen0n · 2017-02-17T07:37:37Z

src/doc/book/src/procedural-macros.md

+```
+
+The compiler needs to know that we handle this attribute and to not respond with an error.
+This is done in the `hello-world-derive`-crate by adding `attributes` to the `proc_macro_derive` attribute:


The hyphen before crate should be replaced by a space.

xen0n · 2017-02-17T07:39:27Z

src/doc/book/src/procedural-macros.md

+
+## Raising Errors
+
+Let's assume that we do not want to accept `Enums` as input to our custom derive method.


The use of Enums is over-emphasis, IMO just enums or enumerations without the inline code block is enough.

JDemler · 2017-02-19T17:17:09Z

Thanks for the nits. They should be resolved now.

steveklabnik · 2017-02-24T04:00:30Z

@bors: r+ rollup

thank you!

bors · 2017-02-24T04:00:31Z

📌 Commit 198208b has been approved by steveklabnik

Add Documentation for Custom Attributes and Error Reporting in Procedural Macros This fixes rust-lang#39821 . I'm not sure if the process of how to access custom attributes should be documented as well. But I feel, that this should rather be documented in `syn`

Rollup of 17 pull requests - Successful merges: #39777, #39815, #39845, #39886, #39892, #39903, #39905, #39914, #39927, #39940, #40010, #40030, #40048, #40050, #40052, #40060, #40071 - Failed merges:

Rollup of 11 pull requests - Successful merges: #39777, #39815, #39845, #39886, #39940, #40010, #40030, #40048, #40050, #40052, #40071 - Failed merges:

gilescope · 2018-04-10T21:58:40Z

Hoping feedback is always welcome: A paragraph pointing to syn with a little example of how to access HelloWorldName = "the best Pancakes" would be really really appreciated on that page. Its not clear from the TokenStream input type - I looked here https://doc.rust-lang.org/proc_macro/struct.TokenStream.html and find no mention of attributes.

trsh · 2018-07-24T15:32:43Z

It's still not written how to read HelloWorldName in macro fn

custom attributes and error reporting docs for procedural macros

5189c4f

rust-highfive assigned steveklabnik Feb 15, 2017

add bash to error-messages

9a39994

steveklabnik suggested changes Feb 15, 2017

View reviewed changes

fixed whitespace issues

9745199

xen0n reviewed Feb 17, 2017

View reviewed changes

Fixed some small issues

198208b

steveklabnik approved these changes Feb 24, 2017

View reviewed changes

GuillaumeGomez mentioned this pull request Feb 24, 2017

Rollup of 11 pull requests #40072

Merged

frewsxcv mentioned this pull request Feb 24, 2017

Rollup of 17 pull requests #40080

Closed

bors added a commit that referenced this pull request Feb 25, 2017

Auto merge of #40072 - GuillaumeGomez:rollup, r=GuillaumeGomez

7932349

Rollup of 11 pull requests - Successful merges: #39777, #39815, #39845, #39886, #39940, #40010, #40030, #40048, #40050, #40052, #40071 - Failed merges:

bors merged commit 198208b into rust-lang:master Feb 25, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Documentation for Custom Attributes and Error Reporting in Procedural Macros #39845

Add Documentation for Custom Attributes and Error Reporting in Procedural Macros #39845

JDemler commented Feb 15, 2017

rust-highfive commented Feb 15, 2017

steveklabnik left a comment

steveklabnik Feb 15, 2017

steveklabnik Feb 15, 2017

steveklabnik Feb 15, 2017

JDemler Feb 16, 2017

steveklabnik Feb 16, 2017

steveklabnik Feb 16, 2017

JDemler Feb 16, 2017

xen0n left a comment

xen0n Feb 17, 2017

xen0n Feb 17, 2017

xen0n Feb 17, 2017

xen0n Feb 17, 2017

xen0n Feb 17, 2017

xen0n Feb 17, 2017

xen0n Feb 17, 2017

JDemler commented Feb 19, 2017

steveklabnik commented Feb 24, 2017

bors commented Feb 24, 2017

gilescope commented Apr 10, 2018

trsh commented Jul 24, 2018



		## Raising Errors
		Let's assume that we do not want to accept `Enums` as input to our custom derive method.

Add Documentation for Custom Attributes and Error Reporting in Procedural Macros #39845

Add Documentation for Custom Attributes and Error Reporting in Procedural Macros #39845

Conversation

JDemler commented Feb 15, 2017

rust-highfive commented Feb 15, 2017

steveklabnik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xen0n left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JDemler commented Feb 19, 2017

steveklabnik commented Feb 24, 2017

bors commented Feb 24, 2017

gilescope commented Apr 10, 2018

trsh commented Jul 24, 2018