Clarify the meaning of `AttributeOrder::KeepFirst` and `AttributeOrder::KeepLast`

1 files changed, 15 insertions, 1 deletions

diff --git a/compiler/rustc_attr_parsing/src/attributes/mod.rs b/compiler/rustc_attr_parsing/src/attributes/mod.rs
index ba7572434df..d466d946cc0 100644
--- a/compiler/rustc_attr_parsing/src/attributes/mod.rs
+++ b/compiler/rustc_attr_parsing/src/attributes/mod.rs
@@ -217,7 +217,14 @@ impl<S: Stage> OnDuplicate<S> {
 // them will be merged in another PR
 #[allow(unused)]
 pub(crate) enum AttributeOrder {
-    /// Duplicates after the first attribute will be an error.
+    /// Duplicates after the first attribute will be an error. I.e. only keep the lowest attribute.
+    ///
+    /// Attributes are processed from bottom to top, so this raises an error on all the attributes
+    /// further above the lowest one:
+    /// ```
+    /// #[stable(since="1.0")] //~ WARNING duplicated attribute
+    /// #[stable(since="2.0")]
+    /// ```
     ///
     /// This should be used where duplicates would be ignored, but carry extra
     /// meaning that could cause confusion. For example, `#[stable(since="1.0")]
@@ -227,6 +234,13 @@ pub(crate) enum AttributeOrder {
     /// Duplicates preceding the last instance of the attribute will be a
     /// warning, with a note that this will be an error in the future.
     ///
+    /// Attributes are processed from bottom to top, so this raises a warning on all the attributes
+    /// below the higher one:
+    /// ```
+    /// #[path="foo.rs"]
+    /// #[path="bar.rs"] //~ WARNING duplicated attribute
+    /// ```
+    ///
     /// This is the same as `FutureWarnFollowing`, except the last attribute is
     /// the one that is "used". Ideally these can eventually migrate to
     /// `ErrorPreceding`.