Fix Bugzilla 24543 - The @future attribute is (almost) undocumented (#3827)

Author: ntrel

spec/attribute.dd

@@ -39,6 +39,7 @@ $(GNAME FunctionAttributeKwd):
 
 $(GNAME AtAttribute):
     $(D @) $(RELATIVE_LINK2 disable, $(D disable))
+    $(D @) $(RELATIVE_LINK2 future, $(D __future))
     $(D @) $(RELATIVE_LINK2 nogc, $(D nogc))
     $(D @) $(DDLINK spec/ob, Live Functions, `live`)
     $(GLINK Property)
@@ -402,6 +403,34 @@ $(GNAME DeprecatedAttribute):
         )
 
 
+$(H2 $(LNAME2 future, `@__future` attribute))
+
+        $(P The `@__future` attribute is used to mark a new symbol which could
+        cause a name clash in another module. The other module using a symbol with the
+        same name will continue to compile as before but will show a deprecation message.
+        The message indicates that the new symbol will break the existing code in future,
+        and the other module should be updated.
+        )
+
+        $(NOTE Currently only methods that implicitly override a `@__future` base class
+        method show a deprecation message.)
+
+        $(P See $(LINK2 https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1007.md,
+        DIP1007) for details.)
+
+        $(COMMENT
+        ---
+        module a;
+        @__future int i;
+
+        module b;
+        import a;
+        import c : i;
+        enum e = i; // Deprecation: `c.i` will conflict with `@__future` symbol `a.i`
+        ---
+        )
+
+
 $(H2 $(LNAME2 visibility_attributes, Visibility Attributes))
 
 $(GRAMMAR

spec/traits.dd

@@ -1185,8 +1185,9 @@ $(H3 $(GNAME isNested))
 $(H3 $(GNAME isFuture))
 
     $(P Takes one argument. It returns `true` if the argument is a symbol
-    marked with the `@future` keyword, otherwise `false`. Currently, only
-    functions and variable declarations have support for the `@future` keyword.)
+    marked with the $(DDSUBLINK spec/attribute, future, `@__future` attribute),
+    otherwise `false`. Currently, only
+    functions and variable declarations have support for the `@__future` keyword.)
 
 $(H3 $(GNAME isDeprecated))