|
| 1 | +# Scope |
| 2 | + |
| 3 | +## Scope of the Reference |
| 4 | + |
| 5 | +The scope of the Rust Reference is to fully describe the syntax and semantics of the Rust language. In this context, the language encompasses: |
| 6 | + |
| 7 | +- Valid syntax and forms. |
| 8 | +- Meaning and interpretation of the syntax. |
| 9 | +- Semantic properties of the runtime behavior. |
| 10 | +- Built-in attributes. |
| 11 | +- Built-in types. |
| 12 | +- *Language items* from the standard library, which directly interface with the language (such as operators desugaring to trait calls). |
| 13 | +- All [editions] of Rust. |
| 14 | + |
| 15 | +## Out of scope |
| 16 | + |
| 17 | +The Reference does not cover: |
| 18 | + |
| 19 | +- Contents of the standard library, unless required to describe other language aspects. |
| 20 | + - The standard library is described in [the standard library API documentation][std]. |
| 21 | +- Introductions or guides to the language. Background familiarity with the language is assumed. A separate [book] is available to help acquire such background familiarity. |
| 22 | +- Recommendations on how to write Rust code. |
| 23 | + - Exceptional cases may be included in a [note] or [warning]. |
| 24 | +- Specifics of tooling provided by the Rust organization, such as `rustc` or Cargo. |
| 25 | + - `rustc` has its own [book][rustc book]. Cargo has a [book][cargo book] that contains a [reference][cargo reference]. |
| 26 | + - In exceptional circumstances, notes may refer to these tools when they have significant relevance. |
| 27 | +- Specifics of which targets exist, or properties of specific targets. See [target-specific behavior] for more details. |
| 28 | +- Unstable features only available on the [nightly channel]. |
| 29 | + - For documentation of unstable features, see the [Unstable Book]. |
| 30 | + - Occasionally the Reference may refer to an unstable feature because it is important to understand the model of stable code. |
| 31 | +- Future changes, with the following exceptions: |
| 32 | + - Language constructs that are designed to specifically allow for future extensions. For example, some syntax is reserved for future use, or some values such as config predicates may be documented as *open*, meaning they may be extended in the future. |
| 33 | + - Notes for [incomplete or undecided behavior] may refer to the future intentions. |
| 34 | + - Notes about deviation from [intended behavior] may mention that the behavior may change. |
| 35 | +- Version history or past behavior. |
| 36 | + - Changes in Rust releases are recorded in the [Release Notes]. Prior releases of the Reference are available as described in [Rust releases]. |
| 37 | +- Historical documentation. |
| 38 | + - This includes documentation such as [RFCs], design documents, reports, blog posts, issues, pull requests, etc. |
| 39 | +- Rationale for most aspects of the language. |
| 40 | + - Rationale may be included in a note in exceptional situations, particularly when a feature is not obvious or has especially useful relevance. |
| 41 | +- `rustc` lints. |
| 42 | + - Lints are documented in the [rustc book][lints]. |
| 43 | + - Lints that have a specific relation to some part of the language may be referred to by name. For example, the `expect` attribute can issue the `unfulfilled_lint_expectations` lint. However, the exact behavior of when the lint is issued is usually not documented in the Reference. |
| 44 | + - Notes may refer to lints when the lint has exceptional relevance to some aspect of the language. |
| 45 | +- Method of translation into executable code, unless required (for example, as it relates to the translation of [inline assembly]). |
| 46 | +- Allowed or disallowed optimizations, unless specifically afforded by the language. |
| 47 | +- Limits on compiler inputs (such as maximum source file size), unless the language explicitly defines specific limits (for example, see [limits] or the [number of `#` symbols in raw strings][lex.token.literal.str-raw.intro]). |
| 48 | + |
| 49 | +## Completeness |
| 50 | + |
| 51 | +Portions of the Reference may be incomplete or undecided. Work is ongoing to complete these sections. New features and changes to the language must be completely documented, unless they involve sections of the language that were previously undocumented. |
| 52 | + |
| 53 | +*Complete* means that the syntax and semantics are sufficiently documented for someone reasonably skilled in the art to fully understand them. However, because the majority of the Reference is written in English prose rather than a rigorous formalism, ambiguities or misunderstandings can arise. If you encounter something unclear, we welcome your feedback through our [issue tracker]. Separate work is ongoing to provide more formal definitions of the language in the future. |
| 54 | + |
| 55 | +## Correctness |
| 56 | + |
| 57 | +The Reference is intended to be correct in all aspects. If errors or ambiguities are discovered, the Reference is updated to correct them. |
| 58 | + |
| 59 | +If there are errors, ambiguities, or conflicts with the `rustc` implementation, we must first determine the [intended behavior](#intended-behavior). Whether something is an error can sometimes be unclear; in those situations, the Reference editors consult: |
| 60 | + |
| 61 | +- The behavior in `rustc`. |
| 62 | +- Historical documentation and communication. |
| 63 | +- Teams in the Rust organization. |
| 64 | + |
| 65 | +## Intended behavior |
| 66 | + |
| 67 | +At times, the actual behavior of the official `rustc` implementation may diverge from the documented or intended behavior. Generally, the Reference documents the intended behavior, even if it differs from the actual behavior in `rustc`. Informational notes may be included to highlight significant discrepancies. These notes may refer to *future-incompatible warnings*, which are lints used by `rustc` to alert users about planned changes. |
| 68 | + |
| 69 | +However, documenting every bug or implementation quirk in `rustc` is out of scope. Only discrepancies that are significant, long-standing, or particularly likely to affect users are mentioned. Minor bugs, temporary implementation issues, or behaviors expected to be fixed in an upcoming release are typically not documented. |
| 70 | + |
| 71 | +## Unspecified behavior |
| 72 | + |
| 73 | +*Unspecified behavior* is behavior that is documented as not explicitly defined, but still covers a well-formed program. This should be a relatively rare concept, as the intent is for programmers to rely on expected behavior in as many areas as possible. Unspecified behavior may change between releases or compilation settings, and may become specified in a future release. |
| 74 | + |
| 75 | +Behavior is typically left unspecified when the language intentionally allows implementation flexibility for optimization or platform-specific concerns, provided the variation does not affect program correctness. Examples include the exact layout of certain types using [the `Rust` representation] or how and when optimization hints such as inlining occur. |
| 76 | + |
| 77 | +Unspecified behavior differs from [undefined behavior](#undefined-behavior) in that all possible outcomes are valid and do not compromise program safety. Programs should not rely on specific unspecified behaviors, as they may vary between compiler versions, optimization levels, or platforms. |
| 78 | + |
| 79 | +Unspecified behavior differs from [incomplete documentation](#completeness) in that the Reference specifically identifies the behavior as intentionally unspecified, whereas incomplete documentation is intended to be specified but has not yet been written. |
| 80 | + |
| 81 | +## Undefined behavior |
| 82 | + |
| 83 | +[*Undefined behavior*][undefined] is compile-time or run-time behavior that is not specified. See the corresponding chapter for a complete description. Other chapters may mention undefined behavior where relevant, but should also link back to the [undefined behavior][undefined] chapter. |
| 84 | + |
| 85 | +## Target-specific behavior |
| 86 | + |
| 87 | +The Reference does not document which targets exist or the properties of specific targets. The Reference may refer to *platforms* or *target properties* where required. Examples of defined target properties include: |
| 88 | + |
| 89 | +- Conditional-compilation keys like [`target_os`] are specified to exist, but not what their values must be. |
| 90 | +- The [`windows_subsystem` attribute] specifies that it only works on Windows platforms. |
| 91 | +- [Inline assembly] and the [`target_feature` attribute] specify the supported architectures. |
| 92 | + |
| 93 | +For a list of targets supported by `rustc`, see [the rustc book][rustc-platforms]. |
| 94 | + |
| 95 | +## Normative and informational content |
| 96 | + |
| 97 | +The Reference contains both normative and informational content. *Normative content* defines the official requirements and specifications of the Rust language: the rules that determine what constitutes valid Rust code and its behavior. *Informational content* provides context, examples, and clarifications that aid understanding but do not define requirements. |
| 98 | + |
| 99 | +Normative content consists of [rules], [grammar productions], and anything else explicitly listed as normative. |
| 100 | + |
| 101 | +Informational content consists of [notes], [examples], [warnings], introductions (rule labels ending in `.intro`), footnotes, and appendices (unless otherwise noted). |
| 102 | + |
| 103 | +[`target_feature` attribute]: attributes.codegen.target_feature |
| 104 | +[`target_os`]: cfg.target_os |
| 105 | +[`windows_subsystem` attribute]: runtime.windows_subsystem |
| 106 | +[book]: ../book/index.html |
| 107 | +[cargo book]: ../cargo/index.html |
| 108 | +[cargo reference]: ../cargo/reference/index.html |
| 109 | +[editions]: introduction.md#editions |
| 110 | +[examples]: introduction.md#examples |
| 111 | +[grammar productions]: notation.md |
| 112 | +[incomplete or undecided behavior]: #completeness |
| 113 | +[Inline assembly]: asm |
| 114 | +[intended behavior]: #intended-behavior |
| 115 | +[issue tracker]: https://github.com/rust-lang/reference/issues |
| 116 | +[limits]: attributes.limits |
| 117 | +[lints]: ../rustc/lints/index.html |
| 118 | +[nightly channel]: ../book/appendix-07-nightly-rust.html |
| 119 | +[note]: conventions.md#notes |
| 120 | +[notes]: introduction.md#notes |
| 121 | +[Release Notes]: https://doc.rust-lang.org/releases.html |
| 122 | +[RFCs]: https://rust-lang.github.io/rfcs/ |
| 123 | +[rules]: introduction.md#rules |
| 124 | +[Rust releases]: introduction.md#rust-releases |
| 125 | +[rustc book]: ../rustc/index.html |
| 126 | +[rustc-platforms]: ../rustc/platform-support.html |
| 127 | +[std]: ../std/index.html |
| 128 | +[target-specific behavior]: #target-specific-behavior |
| 129 | +[the `Rust` representation]: layout.repr.rust |
| 130 | +[Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ |
| 131 | +[warning]: conventions.md#warnings |
| 132 | +[warnings]: introduction.md#warnings |
0 commit comments