Document the `proc_macro` feature in the Unstable Book #41476

abonander · 2017-04-23T06:25:38Z

Discusses the proc_macro feature flag and the features it enables:

Implicit enable of extern_use_macros feature and how to import proc macros
Error handling in proc macros (using panic messages)
Function-like proc macros using #[proc_macro] and a usage example for creating and invoking
Attribute-like proc macros using #[proc_macro_attribute] and a usage example for creating and invoking

abonander · 2017-04-23T06:34:02Z

src/doc/unstable-book/src/language-features/proc-macro.md

+}
+```
+
+`my_macro_user/main.rs`:


Do I need to show adding the dependency on my_macro_crate to my_macro_user/Cargo.toml?

it might be nice

Maybe at the top where I show adding the [lib] proc-macro = true section, so it doesn't get repetitive? Or do we want to make the dependency relationship clearer in this specific example (and presumably in its sibling below as well)?

abonander · 2017-04-23T23:20:16Z

I realized I used "which" a lot and now it's bothering me.

abonander · 2017-04-23T23:39:54Z

I would like to have doctesting work for the code examples but I don't think doctests can test code snippets as separate crates.

steveklabnik

this is a great start 👍

steveklabnik · 2017-04-24T07:22:51Z

src/doc/unstable-book/src/language-features/proc-macro.md

+
+#### Error Reporting
+
+Currently the only support for error reporting from procedural macros is through panics. Any panics in a procedural 


Usually, it's better to write things in a "timeless" way, if that makes any sense. Basically, if we miss updating these docs when different error reporting stuff is added, does this still make sense? With this phrasing, it doesn't, but if you remove the first sentence, it does. We might be able to find a way to re-phrase the first sentence too...

If that's the convention you want to enforce, I won't argue it.

But in my mind, saying "currently" tends to encourage the reader to be a little more forgiving with outdated information (context helps, being the "unstable" book and all). If that first bit was dropped so that it read "The only support for error reporting [...]" and then that fact changed later without the book updating, it would seem... disingenuous? Something like that.

I would also note that using "currently" tells the reader to expect this aspect to change/improve in the future, though I guess they've probably already acknowledged that by this point.

Eh, after some consideration, dropping the whole first sentence seems okay.

(context helps, being the "unstable" book and all)

I think this might be it, that is, it's true that for now, this stuff is not too stable, but we also don't want to do too much massaging once things actually need to go in stable places. It's possible I'm thinking too much of the future here.

I would also note that using "currently" tells the reader to expect this aspect to change/improve in the future,

Right, so the problem with this has been that in the future, changes get made, and then docs don't change, and then they're left with the incorrect impression that changes never happened. It's just tough.

Regardless, all of this is fairly minor and I'm happy to land it either way, to be honest. As you said, it is the unstable book 😄

steveklabnik · 2017-04-24T07:23:04Z

src/doc/unstable-book/src/language-features/proc-macro.md

+Currently the only support for error reporting from procedural macros is through panics. Any panics in a procedural 
+macro implementation will be caught by the compiler and turned into an error message pointing to the problematic 
+invocation. Thus, it is important to make your panic messages as informative as possible: use `Option::expect()`
+instead of `Option::unwrap()` and `Result::expect()` instead of `Result::unwrap()`, and inform the user of the error 


no ()s on function names

Just a note, I like ()s because it distinguishes functions from public fields in this kind of context.

I also prefer it, unfortunately, the RFC process yielded different results 😄

steveklabnik · 2017-04-24T07:23:25Z

src/doc/unstable-book/src/language-features/proc-macro.md

+* A `Display` impl which writes out the contained tokens. Of course, the blanket `ToString` impl applies 
+to this type as well.
+
+### Function-like / Bang-style Procedural Macros


we do need to sort out these names at some point 😄

I'm personally leaning towards "function-like" just because it sounds more formal. "bang" or "bang-style" just does not sound like it belongs in a technical document.

Actually, is mentioning both all that bad? It might help the reader if they later come across discussions where the two terms are used interchangeably.

nudging people toward proper use is a good idea, IMHO. there's no reason to have two names.

steveklabnik · 2017-04-24T07:23:48Z

src/doc/unstable-book/src/language-features/proc-macro.md

+}
+```
+
+`my_macro_user/main.rs`:


it might be nice

steveklabnik · 2017-04-24T07:25:04Z

src/doc/unstable-book/src/language-features/proc-macro.md

+**Note**: invocations of this kind of macro require a wrapping `[]`, `{}` or `()` like regular macros, but these do not 
+appear in the input, only the tokens between them. The tokens between the braces do not need to be valid Rust syntax.
+
+`my_macro_crate/lib.rs`:


I wonder if we should steal the formatting from the book:

Check out the *src/main.rs* file: <span class="filename">Filename: src/main.rs</span> ```rust fn main() { println!("Hello, world!"); } ```

https://raw.githubusercontent.com/rust-lang/book/master/second-edition/src/ch02-00-guessing-game-tutorial.md

At what point does it stop being "stealing" and becomes "following convention"? 😄

abonander · 2017-04-24T15:57:23Z

@steveklabnik Requested revisions made. Now I'm mainly just waiting for an executive decision from either @nrc or @jseyfried on the preferred terminology as mentioned above.

abonander · 2017-04-25T01:54:11Z

@steveklabnik Weird error in the test failure, it's trying to test a slice of an ignored code block...?

Mark-Simulacrum · 2017-04-25T02:07:01Z

I suspect that the placing of the filename directly above the code block is causing the parser (hoedown? pulldown? I don't recall what we're at right now) to misinterpret the code block somehow. Perhaps a blank line would be a good idea.

abonander · 2017-04-25T02:17:13Z

Worth a shot but the other code blocks work fine so it's weird. It's also starting to interpret the code block halfway through it as far as I can tell.

steveklabnik · 2017-04-25T09:15:40Z

/cc @GuillaumeGomez for the weird errors

GuillaumeGomez · 2017-04-25T10:19:52Z

We're back to hoedown so it should be the old (and long running) doc test system. Ping me if you can't figure it out once tests finished.

abonander · 2017-04-25T20:23:37Z

Huh, looks like these latest test failures are truly unrelated.

abonander · 2017-04-26T18:42:20Z

@steveklabnik Can you get bors to retry the build?

GuillaumeGomez · 2017-04-27T14:08:29Z

@bors: retry

alexcrichton · 2017-05-04T18:29:01Z

@steveklabnik it looks like some updates have happened since you last took a look I think, mind taking another look?

abonander · 2017-05-04T19:43:02Z

Still waiting on answers to the questions in the OP as well. @jseyfried @nrc

steveklabnik · 2017-05-09T16:28:39Z

This looks great to me; we still have the naming question to resolve though. Unsure exactly how best to do that...

Mark-Simulacrum · 2017-05-14T15:59:37Z

@jseyfried @nrc Is there a chance you could take a look and provide some thoughts on the naming? Specifically, what do we call function-like / bang-macros?

note: Also pinged @nrc on IRC; jseyfried wasn't present.

nrc · 2017-05-15T00:34:24Z

Hey, sorry I missed the earlier pings - I was on parental leave and then had to rather forcefully clear my inbox.

I definitely prefer 'function-like' to 'bang' macros - I think it is highly likely that readers will not associate ! with "bang" and I think that ! is really an implementation detail of how macros are called, rather than something essential about them.

nrc · 2017-05-15T00:35:49Z

src/doc/unstable-book/src/language-features/proc-macro.md


+* Attribute procedural macros which can be applied to any item which built-in attributes can


I call these 'attribute-like' since they only look like attributes and are implemented differently - also for symmetry with 'function-like'

nrc · 2017-05-15T00:37:58Z

src/doc/unstable-book/src/language-features/proc-macro.md

+the syntax is valid but not in the context in which the macro is invoked, an error is thrown outside the macro.
+
+* A `Display` impl which writes out the contained tokens. Of course, the blanket `ToString` impl applies 
+to this type as well.


I wouldn't describe these as the main APIs - they are kind of a stop-gap measure for custom derives. Macro authors should prefer using quote! to create tokens. (And of course more APIs will be arriving in the future).

nrc · 2017-05-15T00:39:02Z

src/doc/unstable-book/src/language-features/proc-macro.md

+
+### Function-like / Bang-style Procedural Macros
+
+These are procedural macros that are invoked like `macro_rules!` macros. They are declared as public functions in crates 


terminology nit - I prefer 'declarative macros' to 'macro_rules! macros' since the former is a descriptive name and the latter is a detail of how they are (currently) declared.

abonander · 2017-05-15T01:30:06Z

@nrc nits fixed

steveklabnik · 2017-05-15T13:40:40Z

r? @nrc

nrc · 2017-05-16T01:35:47Z

@bors: r+

abonander · 2017-05-16T03:41:35Z

@nrc squashed and PR post cleaned up.

Mark-Simulacrum · 2017-05-16T03:43:12Z

@bors r=nrc

bors · 2017-05-16T03:43:12Z

📌 Commit e4208d5 has been approved by nrc

bors · 2017-05-16T04:02:41Z

⌛ Testing commit e4208d5 with merge 88d44aa...

bors · 2017-05-16T05:00:13Z

💔 Test failed - status-travis

abonander · 2017-05-16T05:38:54Z

Can I get an @bors retry

abonander · 2017-05-16T08:49:38Z

Ugh, it's hitting a wall with the broken-link-checker, on a relative link to the chapter for use_extern_macros. Is there any guidelines here?

steveklabnik · 2017-05-16T13:06:47Z

Hm, I am not sure why it fails in that case, looks right to me. @frewsxcv any ideas?

alexcrichton · 2017-05-16T14:34:30Z

It looks like CI is still failing?

[00:43:59] Linkcheck (x86_64-unknown-linux-gnu)
[00:43:59] unstable-book/print.html:1457: broken link - unstable-book/use-extern-macros.html
[00:43:59] unstable-book/language-features/proc-macro.html:87: broken link - unstable-book/use-extern-macros.html
[00:44:04] thread 'main' panicked at 'found some broken links', /checkout/src/tools/linkchecker/main.rs:49
[00:44:04] note: Run with `RUST_BACKTRACE=1` for a backtrace.
[00:44:04] 
[00:44:04] 
[00:44:04] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools/x86_64-unknown-linux-gnu/release/linkchecker" "/checkout/obj/build/x86_64-unknown-linux-gnu/doc"
[00:44:04] expected success, got: exit code: 101
[00:44:04] 
[00:44:04] 
[00:44:04] Build completed unsuccessfully in 0:08:50
[00:44:04] make: *** [check] Error 1
[00:44:04] Makefile:54: recipe for target 'check' failed

frewsxcv · 2017-05-16T15:36:26Z

@abonander can you try rebasing this off master? there's a chance this could be fixed with #41992, not entirely sure though what's going on with the linkchecker

abonander · 2017-05-16T22:03:58Z

Rebased, let's see.

abonander · 2017-05-17T00:11:27Z

I think the link is supposed to be to language-features/use-extern-macros.html, which doesn't really make sense because proc-macro.html is in the same directory, so just linking to the file should be sufficient. Instead, it's assuming a base url of <docs root>/unstable-book which is why the broken link is unstable-book/use-extern-macros.html when it should be unstable-book/language-features/use-extern-macros.html.

frewsxcv · 2017-05-17T03:51:31Z

which doesn't really make sense because proc-macro.html is in the same directory, so just linking to the file should be sufficient

So it turns out that for subdirectories (like library-features/), mdbook will automatically include a <base href="../"> tag which is presumably why the library-features/ prefix is needed. Considering this is causing confusion, I think mdbook should stop using <base> so this is more obvious.

Anyways, tests seem to be passing now so:

@bors r=nrc

bors · 2017-05-17T03:51:32Z

📌 Commit e616d12 has been approved by nrc

bors · 2017-05-17T04:21:12Z

⌛ Testing commit e616d12 with merge 42e3732...

Document the `proc_macro` feature in the Unstable Book Discusses the `proc_macro` feature flag and the features it enables: * Implicit enable of `extern_use_macros` feature and how to import proc macros * Error handling in proc macros (using panic messages) * Function-like proc macros using `#[proc_macro]` and a usage example for creating and invoking * Attribute-like proc macros using `#[proc_macro_attribute]` and a usage example for creating and invoking [Rendered](https://github.com/abonander/rust/blob/book_proc_macro/src/doc/unstable-book/src/language-features/proc-macro.md)

bors · 2017-05-17T06:49:00Z

☀️ Test successful - status-appveyor, status-travis
Approved by: nrc
Pushing 42e3732 to master...

rust-highfive assigned steveklabnik Apr 23, 2017

abonander commented Apr 23, 2017

View reviewed changes

abonander force-pushed the book_proc_macro branch from 102a955 to aae1e64 Compare April 23, 2017 23:32

steveklabnik reviewed Apr 24, 2017

View reviewed changes

carols10cents added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Apr 24, 2017

abonander mentioned this pull request Apr 24, 2017

proc_macro: implement TokenTree, TokenKind, hygienic quote!, and other API #40939

Merged

alexcrichton added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels May 4, 2017

nrc reviewed May 15, 2017

View reviewed changes

rust-highfive assigned nrc and unassigned steveklabnik May 15, 2017

abonander changed the title ~~[WIP] Document the proc_macro feature in the Unstable Book~~ Document the proc_macro feature in the Unstable Book May 16, 2017

abonander force-pushed the book_proc_macro branch from 5cc69d7 to e4208d5 Compare May 16, 2017 03:41

Mark-Simulacrum added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 16, 2017

abonander force-pushed the book_proc_macro branch from e4208d5 to 0089e22 Compare May 16, 2017 05:38

arielb1 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels May 16, 2017

abonander force-pushed the book_proc_macro branch from 0089e22 to 82488df Compare May 16, 2017 21:54

Document the proc_macro feature in the Unstable Book

e616d12

abonander force-pushed the book_proc_macro branch from 82488df to e616d12 Compare May 17, 2017 00:08

frewsxcv mentioned this pull request May 17, 2017

Usages of the <base> tag causes confusion rust-lang/mdBook#279

Closed

bors merged commit e616d12 into rust-lang:master May 17, 2017


		#### Error Reporting

		Currently the only support for error reporting from procedural macros is through panics. Any panics in a procedural


		* Attribute procedural macros which can be applied to any item which built-in attributes can


		### Function-like / Bang-style Procedural Macros

		These are procedural macros that are invoked like `macro_rules!` macros. They are declared as public functions in crates

Document the proc_macro feature in the Unstable Book #41476

Document the proc_macro feature in the Unstable Book #41476

Conversation

abonander commented Apr 23, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abonander Apr 24, 2017 • edited Loading

Choose a reason for hiding this comment

abonander commented Apr 23, 2017

abonander commented Apr 23, 2017

steveklabnik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abonander Apr 24, 2017 • edited Loading

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

abonander Apr 24, 2017 • edited Loading

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

abonander commented Apr 24, 2017

abonander commented Apr 25, 2017

Mark-Simulacrum commented Apr 25, 2017

abonander commented Apr 25, 2017

steveklabnik commented Apr 25, 2017

GuillaumeGomez commented Apr 25, 2017 • edited Loading

abonander commented Apr 25, 2017

abonander commented Apr 26, 2017

GuillaumeGomez commented Apr 27, 2017

alexcrichton commented May 4, 2017

abonander commented May 4, 2017

steveklabnik commented May 9, 2017

Mark-Simulacrum commented May 14, 2017

nrc commented May 15, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abonander commented May 15, 2017

steveklabnik commented May 15, 2017

nrc commented May 16, 2017

abonander commented May 16, 2017

Mark-Simulacrum commented May 16, 2017

bors commented May 16, 2017

bors commented May 16, 2017

bors commented May 16, 2017

abonander commented May 16, 2017

abonander commented May 16, 2017

steveklabnik commented May 16, 2017

alexcrichton commented May 16, 2017

frewsxcv commented May 16, 2017

abonander commented May 16, 2017

abonander commented May 17, 2017

frewsxcv commented May 17, 2017

bors commented May 17, 2017

bors commented May 17, 2017

bors commented May 17, 2017

Document the `proc_macro` feature in the Unstable Book #41476

Document the `proc_macro` feature in the Unstable Book #41476

abonander commented Apr 23, 2017 •

edited

Loading

abonander Apr 24, 2017 •

edited

Loading

abonander Apr 24, 2017 •

edited

Loading

abonander Apr 24, 2017 •

edited

Loading

GuillaumeGomez commented Apr 25, 2017 •

edited

Loading