godotengine / godotengine/godot-docs

PackedScene Doc enchancements

Open
#4,233 0 comments 0 reactions 0 assignees View on GitHub
area:class reference enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

https://godot-es-docs.readthedocs.io/en/latest/classes/class_packedscene.html#class-packedscene-instance

I first came across that doc a few days ago and was confused then (even mentioned it in an issue, but tangentially).
Today I learnt what PackedScene actually does from the step-by-step guide (https://godot-es-docs.readthedocs.io/en/latest/getting_started/step_by_step/scripting_continued.html#instancing-scenes)

Issues:

* It's not clear what the class does from the brief description. It's too brief and to me at least it uses too-technical language.
* The long description doesn't really explain what it does either.
* What does "Requires tools compiled." mean (GenEditState)? Seems stilted.
* "If passed to instance, provides local scene resources to the local scene." - I don't really understand what that means either. Even with the context that it probably relates to editing in some way.
* "Provides access to operations and checks that can be performed on the scene resource itself." - If you're keeping this sentence, please put a comma after "operations" to provide clear delineation between it and checks.
* "When saving, the node as well as all the node it owns get saved (see owner property on Node)." - grammatical error ("as well as all the node"). It's also not really clear what's going on here.
* The prose says "CollisionObject2D (collision).", but the code says: `CollisionShape2D.new()`
* "Only rigid is owned by node and pack will therefore only save those two nodes, but not collision." - I'm guessing this is trying to say that pack can only pack the node and it's children, but not grandchildren or lower? It would be clearer if it was spelt out in those terms (same for the `pack()` method description). Also, could use a comma after the first "node", again for clearer delineation.
* `_bundled` -> "Available keys include..." this section could be better laid out for improved readability. I'd suggest putting each grouping on its own line. Also use [code] for the keys, or [i], [b].
* `pack()` description doesn't explain what it actually does, it only has method caveats.
* The text "See Node.set_owner" in `pack()` should be a link to: https://godot-es-docs.readthedocs.io/en/latest/classes/class_node.html#class-node-owner

(Note that though it could come across as such, I'm not so arrogant as to think that just because I don't understand something doesn't mean no-one does. ;-) My thinking is that given my background (native English, highly technical, and very experienced in other software areas), if I'm struggling to parse/read/understand a doc, it's likely others will too.)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.