Overhaul NodePath documentation

[Mickeon]

Currently a draft because it feels like more can still be done. I would love your assistance!

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

... Man, this doc has been collecting so much dust!

General

• Made the wording match how other classes are documented more closely;
• Changed most self-referential mentions of "NodePath" to "node path";
• Simplified and clarified the wording marginally. In particular:
  • "prepended" -> "prefixed";
  • "make up" -> "compose";
  • "subnames" -> "property subnames".
  • "gets" -> "returns".
• Remove mentions of "resource and properties" and similar.
  • All Resources are properties in the context of a NodePath. Not to mention that NodePaths may not necessarily point to a Resource type.
• Use GDScript's literal syntax for NodePaths (^"") whenever applicable.
• Modified misleading recurring examples:
  - Path2D/PathFollow2D/Sprite2D:texture:load_path. But load_path isn't even a real thing.
  - There also were a lot of Path2D and PathFollow2D everywhere.
  An outstandingly baffling choice for a class that is literally a path.
• Overhaul the leading description extensively.
  • Basically all of the topics that need to be talked about have been rearranged to hopefully be easier to digest.
  • Add examples for property paths.

---

Constructors

NodePath(String)

• Removed the "absolute VS. relative" explanation.
  • This is not the place to explain it. It's already been done.
  • "Absolute paths are only valid in the global scene tree, not within individual scenes" this is just not true, too?
  • "In a relative path, "." and ".." indicate the current node and its parent." is a bit misleading, too.
    You may use .. in the middle an absolute path just fine if you really, really wanted to

Methods

get_as_property_path

• Specify it returns a copy of the node path.
• Make the examples less verbose and more readable.

get_concatenated_names, get_concatenated_subnames

• Specify that a StringName is returned.
  • Without looking closer, it may be easy to assume an Array of Strings is returned.

get_name, get_subname

• Modified examples to be slightly less generic and potentially confusing.
• Describe what happens when the index is out of bounds.

hash

• Add note on hash comparisons.
  • This note was also added in the String documentation previously.

is_absolute

• Modified description to be considerably less awkward.

is_empty

• "Returns true if the node path is empty.". Wow, thanks!

---

Feedback is very, very welcome.

[MewPurPur]

Idk about using two examples here. Both could be either.

[Mickeon]

I tried trimming it to a single example that proposes both possible nodes, but the example does look "uglier" and not as tidy as a result.

[MewPurPur]

Another note, we could mention that "..", "." also count as names.

[Mickeon]

Updated PR to address the majority of the review above, along with several tweaks especially to the leading description.

Another note, we could mention that "..", "." also count as names.

Both .. and . are now documented in the leading description. Some examples have changed to use .. as well.

I feel like more can be done (namely, the short description absolutely needs to change), but it currently is in a pretty good state.

[Mickeon]

Very minor rebase after conflict.

[Mickeon]

Rebased to force the Linux test to start, hopefully without bugging out.

[AThousandShips]

Otherwise the language and style looks good

[Mickeon]

Accepted all of the above suggestions. Thank you.

[Mickeon]

Rebased after a "conflict" (it didn't really matter, it is overridden entirely).

It would be nice to have this for 4.3 along with the other "polishing" changes.

[akien-mga]

Thanks!

[Mickeon]

At long last, thank you. A few of these long-standing ones shall remain.