Clarification of terms

[pavelrappo]

The rustdoc documentation mentions a number of terms which I haven't found the definitions for. Might it be that they are either undefined or defined elsewhere?

• "compiltest" from https://doc.rust-lang.org/rustdoc/unstable-features.html#--enable-per-target-ignores-allow-ignore-foo-style-filters-for-doctests
• "Attribute", "annotation", and "directive" seem to be used interchangeably here https://doc.rust-lang.org/rustdoc/documentation-tests.html#attributes

[pavelrappo]

Could compiltest be a simple typo? (There's the compiletest utility; note "e" in its name.)

[GuillaumeGomez]

compiltest is definitely a typo. Sending a quick fix.

[justjosias]

It looks like blocks are being "annotated" with "directives" and "attributes", where:

• annotation is adding the directive or attribute,
• directives tell what should be done with the block (such as, ignore), and
• attributes give the compiler information about the block (such as, text, which means it simply represents text the compiler can ignore).

So I don't think much needs to be changed, unless this needs to be made more explicit somehow.

[njasm]

I can understand and relate with the Attribute title of that documentation section being confusing.

Rust already defines Attributes. For instance cfg and others in the context of the language itself. Inner or Outer ones.
ex. #[test] or #![foo = "bar"]
cf. https://doc.rust-lang.org/reference/attributes.html

Getting back to the documentation, the text details directives that exist and can be used in the context of rustdoc and code that might be testable.

So, I suggest to:

1. Change that section's (https://doc.rust-lang.org/rustdoc/documentation-tests.html#attributes) title to Directives
2. do a pass on the rest of that chapter's text and remove/refactor text into directive/s where we might be using attribute/s or annotation/s.

PS - O wrote more to explaining the rational of my suggestion, than I'll have to write to eventually fix this issue, if you all agree ofc. 😅