Tweak SceneTree Documentation

[Mickeon]

Introduction

Continuation of #67072, #67100, #67208, #67718,... #67880 and #68560...

Here a big list of changes. Someone reading this may take it as a future point of reference. Not just that, but some information deemed important by the maintainers could have been lost during the rewrite. Criticism is encouraged.

Do note that some exceptions or unexplained changes may be present all around. These are typically done to improve the flow of the sentence.

General

• Made the wording match how other classes are documented a lot more closely.

• Made use of [param] and several other strong references more often.

• Stripped awkward, needlessly long sentences.

• Changed words where it felt necessary, where they could be mistaken for another concept of Godot's API, where technical terms are more appropriate. For example:

  • "whenever" -> "when";
  • "group members"/"members of group" -> "nodes added to".
    • Saying "members" can make it seem like a new concept or "mechanic" is being introduced, but it really is something exclusive between Node and SceneTree, so it is very worth being specific here.

• Replaced several self-links to this class ([SceneTree]) with "tree".

  • The consensus is that self-links within the same class end up making descriptions much less readable, when the subject is "this current object". From RocketChat:

  KoBeWi: It's used, but not consistently. Probably better to not overuse it.

  Me: Like, it works and may be nice for methods like get_node_and_resource() because there, you have to explain the return value accurately. So you do not say "the node" or "a node", you say [Node] because you refer to a Node class object, and in those cases it makes it a lot clearer.

  YuriSizov: I agree that sometimes this gets obnoxious and that we shouldn’t use it when talking about specific instances of a class [...] this looks a bit misleading, as if [Tween] is a singleton of sorts.

Methods

create_timer	... Made parameter descriptions match the rest of the documentation. Merged footnote into the first paragraph.
get_frame	"Returns the current frame number [...]" Thank you...?
get_nodes_in_group	"Returns a list of all nodes assigned to the given group." So all of them? Every single one in the whole engine?
has_group	"Returns true if the given group exists." This is closer to how it works internally. Saying it like this is incredibly vague. You cannot even fetch all groups present in the SceneTree.

Properties

paused	"_process, _physics_process and _input will not be called anymore in nodes." Not quite. This is not accounting for all of the various Node.process_modes available.
root	Expanded description considerably. Added crash warning.

Signals

tree_process_mode_changed

Made consistent with other signal descriptions.

Constants

GROUP_CALL_DEFAULT GROUP_CALL_REVERSE GROUP_CALL_DEFERRED GROUP_CALL_UNIQUE

"Call a group" Groups are not objects and cannot be called. Let's not muddy the waters.

---

Feedback is very, very welcome.

[Mickeon]

@RedMser Check revisions of the issues above if you'd like.

[RedMser]

The changes look great! :)

[Mickeon]

Noticed a few mistakes, feeling like more can be done about them in the upcoming days.

[Mickeon]

Rebased.

[Mickeon]

Rebased (again)...!

[Mickeon]

Rebased. I'm quite content with this.

[Mickeon]

Rebased after further tweaks to the documentation had been made.

[Mickeon]

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

[Mickeon]

Shockingly there's no conflicts. Are we okay to have this for 4.3?

[mhilbrunner]

LGTM. Maybe a rebase to current master would be a good idea still, but this looks good to go.

[Mickeon]

Gonna go through a second pass through history myself to see if any information was lost accidentally.

[Mickeon]

Pheeeuw. There are several commits such as:

• e5f2c44
• bddf246
• 4354cd8
• a5fe392
• ab01dc5...

that added new documentation and I'm not particularly fond of the way they are worded. I would tweak it more, but no more delaying this PR.

With that said, yes. 0ce0c11 was "lost". For SceneTree's has_group:

Returns [code]true[/code] if the given group exists.
A group exists if any [Node] in the tree belongs to it (see [method Node.add_to_group]). Groups without nodes are removed automatically.

Which my PR simply summarizes... I'd say a bit better without needing to spell it out too much? I can let people decide:

Returns [code]true[/code] if a node added to the given group [param name] exists in the tree.

[akien-mga]

Thanks!