From 15f32c54079c2697440717ca3b73e3b525fa773c Mon Sep 17 00:00:00 2001
From: Danil Alexeev <danil@alexeev.xyz>
Date: Sat, 27 May 2023 12:57:23 +0300
Subject: [PATCH] GDScript: Add mention that `@onready @export` doesn't work as
 expected

---
 .../scripting/gdscript/gdscript_basics.rst    | 37 +++++++++++++++----
 .../gdscript_documentation_comments.rst       |  1 -
 2 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst
index 4c7c02c27..35f80d046 100644
--- a/tutorials/scripting/gdscript/gdscript_basics.rst
+++ b/tutorials/scripting/gdscript/gdscript_basics.rst
@@ -404,11 +404,11 @@ between parentheses and separated by commas.
 
 Both of these are the same::
 
-    @onready
-    @export_node_path("TextEdit", "LineEdit")
-    var input_field
+    @annotation_a
+    @annotation_b
+    var variable
 
-    @onready @export_node_path("TextEdit", "LineEdit") var input_field
+    @annotation_a @annotation_b var variable
 
 .. _doc_gdscript_onready_annotation:
 
@@ -435,6 +435,29 @@ can replace the above code with a single line::
 
     @onready var my_label = get_node("MyLabel")
 
+.. warning::
+
+    Applying ``@onready`` and any ``@export`` annotation to the same variable
+    doesn't work as you might expect. The ``@onready`` annotation will cause
+    the default value to be set after the ``@export`` takes effect and will
+    override it::
+
+        @export var a = "init_value_a"
+        @onready @export var b = "init_value_b"
+
+        func _init():
+            prints(a, b) # init_value_a <null>
+
+        func _notification(what):
+            if what == NOTIFICATION_SCENE_INSTANTIATED:
+                prints(a, b) # exported_value_a exported_value_b
+
+        func _ready():
+            prints(a, b) # exported_value_a init_value_b
+
+    Therefore, the ``ONREADY_WITH_EXPORT`` warning is generated, which is treated
+    as an error by default. We do not recommend disabling or ignoring it.
+
 Comments
 ~~~~~~~~
 
@@ -911,7 +934,7 @@ want to assign consecutive integers to some constant.
 ::
 
     enum {TILE_BRICK, TILE_FLOOR, TILE_SPIKE, TILE_TELEPORT}
-    
+
     # Is the same as:
     const TILE_BRICK = 0
     const TILE_FLOOR = 1
@@ -930,10 +953,10 @@ a dictionary can also be used with a named enum.
 ::
 
     enum State {STATE_IDLE, STATE_JUMP = 5, STATE_SHOOT}
-    
+
     # Is the same as:
     const State = {STATE_IDLE = 0, STATE_JUMP = 5, STATE_SHOOT = 6}
-    
+
     func _ready():
         # Access values with Name.KEY, prints '5'
         print(State.STATE_JUMP)
diff --git a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst
index eeac476f0..522905531 100644
--- a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst
+++ b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst
@@ -106,7 +106,6 @@ Examples
 
     ## If the member has any annotation, the annotation should
     ## immediately precede it.
-    @export
     @onready
     var v3 := some_func()