mirror/godot
2
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2024-12-09 10:09:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve C# documentation for FileAccess and DirAccess

Browse Source 
- Adds using statements to C# examples to ensure the resources are freed after usage
- Adds explanation about the importance of disposing the FileAccess now that we don't have a close method
This commit is contained in:
Raul Santos 2022-09-19 18:42:31 +02:00
parent 6f5704d86f
commit 95393c310d
No known key found for this signature in database
GPG Key ID: B532473AE3A803E4
2 changed files with 12 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/classes/DirAccess.xml
View File

@ -27,7 +27,7 @@
[csharp]
public void DirContents(string path)
{
var dir = DirAccess.Open(path);
using var dir = DirAccess.Open(path);
if (dir != null)
{
dir.ListDirBegin();

16
doc/classes/FileAccess.xml
View File

@ -20,24 +20,30 @@
[csharp]
public void Save(string content)
{
var file = FileAccess.Open("user://save_game.dat", File.ModeFlags.Write);
using var file = FileAccess.Open("user://save_game.dat", File.ModeFlags.Write);
file.StoreString(content);
}
public string Load()
{
var file = FileAccess.Open("user://save_game.dat", File.ModeFlags.Read);
using var file = FileAccess.Open("user://save_game.dat", File.ModeFlags.Read);
string content = file.GetAsText();
return content;
}
[/csharp]
[/codeblocks]
In the example above, the file will be saved in the user data folder as specified in the [url=$DOCS_URL/tutorials/io/data_paths.html]Data paths[/url] documentation.
There is no method to close a file in order to free it from use. Instead, [FileAccess] will close when it's freed, which happens when it goes out of scope or when it gets assigned with [code]null[/code].
[codeblock]
There is no method to close a file in order to free it from use. Instead, [FileAccess] will close when it's freed, which happens when it goes out of scope or when it gets assigned with [code]null[/code]. In C# the reference must be disposed after we are done using it, this can be done with the [code]using[/code] statement or calling the [code]Dispose[/code] method directly.
[codeblocks]
[gdscript]
var file = FileAccess.open("res://something") # File is opened and locked for use.
file = null # File is closed.
[/codeblock]
[/gdscript]
[csharp]
using var file = FileAccess.Open("res://something"); // File is opened and locked for use.
// The using statement calls Dispose when going out of scope.
[/csharp]
[/codeblocks]
[b]Note:[/b] To access project resources once exported, it is recommended to use [ResourceLoader] instead of the [FileAccess] API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package.
[b]Note:[/b] Files are automatically closed only if the process exits "normally" (such as by clicking the window manager's close button or pressing [b]Alt + F4[/b]). If you stop the project execution by pressing [b]F8[/b] while the project is running, the file won't be closed as the game process will be killed. You can work around this by calling [method flush] at regular intervals.
</description>