Are annotations explained?

[jeremyfrench]

Hi I've been reading the 2nd edition but this issue also seems to apply to the 2018 one.

The book has in general done a very good job of explaining things as you read, or telling you that something will be explained later.

However while reading about derived traits (in section 5.2) I read this

Rust does include functionality to print out debugging information, but we have to explicitly opt-in to make that functionality available for our struct. To do that, we add the annotation #[derive(Debug)] just before the struct definition, as shown in Listing 5-12:

This shows the code to add, but it does not seem to explain what annotations are and how they work. It is perhaps the fist instance in this book where I have been left wondering about how something works.

I was expecting something like 'we talk about annotations in more detail in chapter X', or conversely having them mentioned after comments in the common language constructs section.

[steveklabnik]

They're called "attributes" and they're largely mentioned in passing. We could do a better job with them for sure.

[steveklabnik]

@carols10cents , do you have any idea if and where we would fit more in about attributes?

[nealmcb]

I concur that helping newbies like me find documentation on attributes, which are quite ubiquitous but hard to search for, is important.

I found myself searching (ctrl-f in browser) in the documentation for '#' and 'pound' to no avail. A google search yielded this laconic explanation: Those pound sign thingies

As a simple step in that direction, I've added both a pound sign and the word Attribute to the title of the first place they are introduced: Chapter 11 on Testing.

Chapter 19 on macros covers more of them.

[abentley]

As a newbie (with a Python background), "5.2 An Example Program Using Structs" left me with the impression that there is a first-class feature named "Annotations", and I then tried to find documentation for. Calling #[derive(Debug)] either a "derive macro" or an "attribute" would have made it easier to find documentation on them.

[abentley]

Also, I find the wording "attribute-like macro" confusing. It makes me wonder what makes them not true attributes. But they are attributes as best as I can tell-- they start with #[ and end with ], which is the syntax for an outer attribute: https://doc.rust-lang.org/reference/attributes.html#attributes

Now, the macro definitions themselves aren't attributes, but they're not "attribute-like" either.

The Rust reference refers to them as "attribute macros". https://doc.rust-lang.org/reference/procedural-macros.html#attribute-macros and I think it would be good use terminology that's consistent with the reference.

[steveklabnik]

The historical reason they were called "attribute-like macros" is because they are macros, but they look like attributes. It is true that they are attributes. It really depends on where you put the focus.

I do think that, if the lang team wants to call them "attribute macros," that's fine by me. I'm happy to do whatever the lang team prefers wtih regards to naming here.