Thoughts on updating documentation/examples

[jkaye2012]

Thanks for the fantastic library!

I have been reading through documentation and examples to learn about Rocket. One thing that confused me is the use of macro_use, extern crate, and serde_derive, none of which I believe are necessary any more (or at least they do not appear to be in my testing). For example, the tera_template example currently begins with:

#[macro_use] extern crate rocket;
#[macro_use] extern crate serde_derive;

But I am able to serve templates through routes with:

use rocket::{get, routes};
use rocket_contrib::templates::Template;
use serde::Serialize;

Of course, I have the serde "derive" feature enabled.

I also noticed another line in the doc that seems to perhaps not be currently, namely that #![feature(proc_macro_hygiene, decl_macro)] must be in the crate entrypoint; I have it instead in a library module and things are working well.

I would be happy to submit a pull request containing this kind of update, but wanted to get some feedback on all of this first. Maybe there's some reason that I'm unaware of that the currently documented way is preferred? I'm relatively new to Rust, so it's hard for me to know.

Thanks!

[jebrosen]

Thanks for bringing this up! The examples were all written before Rust 2018, and some things were not fully updated.

• IIRC leaving #[macro_use] extern crate rocket; was a deliberate style choice: this form allows you to use #[get], #[post], and so on in any module without importing the attributes individually. That conversation is probably somewhere in Rust 2018 #1013.
• serde_derive should definitely be switched; I believe what you described is indeed the recommended form to use today.

#![feature(proc_macro_hygiene, decl_macro)] must be in the crate entrypoint; I have it instead in a library module and things are working well.

If by "a library module" you are referring to lib.rs, then that is indeed the crate entrypoint (of the library crate). If you mean any other module, you should be seeing a warning: crate-level attribute should be in the root module and errors where those features are actually used.

I would be happy to submit a pull request containing this kind of update, but wanted to get some feedback on all of this first.

We are happy to see pull requests, and docs/examples updates are usually pretty quick and easy for us to review and merge.

[jkaye2012]

Great, that makes sense. I'll try to put something together when I have time. Thanks again!

[songroom2016]

can add an example of compression( such as gzip....)?
i think that compression is important .