From e96c67d7256a5d10335187ebcebea1682a491348 Mon Sep 17 00:00:00 2001
From: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>
Date: Sat, 24 Feb 2024 12:09:34 +0100
Subject: [PATCH] Clarify behavior of opening a new file in `FileAccess`

The containing directory must exist for this to succeed.

(cherry picked from commit a775d8bf5abdde5c1b5106dfa3686deb559eee62)
---
 doc/classes/FileAccess.xml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml
index 261e039cb03..425d88c55ac 100644
--- a/doc/classes/FileAccess.xml
+++ b/doc/classes/FileAccess.xml
@@ -463,12 +463,14 @@
 		</constant>
 		<constant name="WRITE" value="2" enum="ModeFlags">
 			Opens the file for write operations. The file is created if it does not exist, and truncated if it does.
+			[b]Note:[/b] When creating a file it must be in an already existing directory. To recursively create directories for a file path, see [method DirAccess.make_dir_recursive]).
 		</constant>
 		<constant name="READ_WRITE" value="3" enum="ModeFlags">
 			Opens the file for read and write operations. Does not truncate the file. The cursor is positioned at the beginning of the file.
 		</constant>
 		<constant name="WRITE_READ" value="7" enum="ModeFlags">
 			Opens the file for read and write operations. The file is created if it does not exist, and truncated if it does. The cursor is positioned at the beginning of the file.
+			[b]Note:[/b] When creating a file it must be in an already existing directory. To recursively create directories for a file path, see [method DirAccess.make_dir_recursive]).
 		</constant>
 		<constant name="COMPRESSION_FASTLZ" value="0" enum="CompressionMode">
 			Uses the [url=https://fastlz.org/]FastLZ[/url] compression method.