godotengine / godotengine/godot-docs
PackedScene Doc enchancements
- 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.