Overhaul OS documentation

[Mickeon]

Draft because more could be done soon. I would love your assistance!

Continuation of similar past efforts with the same goal of refreshing the documentation up a notch.

This is particularly prickly due of the sheer size. There's also a constant fear of possibly losing important information, or making use of incorrect technical terms. A lot of the time is spent reading the original documentation and looking at the source code, too. Fortunately, a decent majority of it is written... quite up to date, too.

• Made the wording match how other classes are documented A LOT more closely;
  • Simplified wording which may be seen as awkward to read, kinda like this very sentence;
  • Use the present simple over future tense when applicable (will return -> returns);
  • Turned some long-winded sentences into notes at the end (and viceversa);
  • Turned some multiple paragraphs into lists;
• Link to other methods and parameters more often;
• Add more examples all around;
• Describe ERR_* constants return values;
• Note more methods moved out of the OS class in the transition to Godot 4;
• All SystemDir constants' descriptions have been prefixed with "Refers to":
  • They could be mistaken to be constant strings, otherwise.

---

close_midi_inputs, get_connected_midi_inputs, open_midi_inputs

• Link the methods between one another.

get_cmdline_user_args

• Rework description entirely.
  • The previous one was a bit unorganized.

get_keycode_string, find_keycode_from_string

• Add considerably more examples.

request_permission, revoke_granted_permissions

• Rework description entirely.
  • The previous one was absolutely not formatted the same as the rest of the documentation.

get_user_data_dir

• Mention ProjectSettings.application/config/use_custom_user_dir directly.

---

Feedback is very, very welcome, even in the draft state. And especially right now. This class is huge and very technical.

In fact, I would like to propose a few questions that may help with this cause:

• "Web platform" or "Web platforms"? Capitalized "Web" or not?
• Is OS.move_to_trash() really implemented only on Android, Linux, macOS and Windows?
• Do OS.request_permission and OS.request_permission return true when permissions are granted successfully?
• What does OS.set_use_file_access_save_and_swap really do?

[bruvzg]

What does OS.set_use_file_access_save_and_swap really do?

If enabled when opening a file for writing, a temporary file is used first, and only when it's closed it is renamed or used to replace an existing file. This is useful in case the original file is opened by other app, scanned by antivirus for example.

[Mickeon]

Pushed a commit that also attempts to address the above comments. I hope you check again.

[Mickeon]

How did the latest unit test even fail?

[YuriSizov]

How did the latest unit test even fail?

Unit tests didn't fail, but there is a problem with thread sanitizer runs. It's not related to your PR and seems to happen sporadically, a re-run fixed it.

[Mickeon]

Rebased after #81416

[Mickeon]

Pushed changes that accept the C# suggestions above. Thank you @raulsntos for the additional attention to this PR.

Changes made.

[Mickeon]

Rebased after:

• Validate code tags for class and member references #82691
• Web: Clarify that OS.get_unique_id is not supported #82441

Would be nice for this to be taken a look at sooner than later

[AThousandShips]

Some minor changes, style looks good otherwise, can't speak for the factual correctness however so someone else needs to verify

[Mickeon]

Addressed the above feedback. Thank you.

I also moved the mention of kill in the crash method description outside of the note, because it is directly related.

[akien-mga]

Only skimmed through the changes, looks good overall.

[Mickeon]

Reverted that comma, but also updated the midi methods' descriptions taking them from #86693. So, whichever gets merged first, they're the same.

[akien-mga]

Thanks!