Add manual pages and content for upcoming GDScript trait system #10393
Conversation
AThousandShips
added
enhancement
area:manual
Add trait-related keywords to syntax highlighting Update style guide and static typing pages Currently, the style guide uses what seem like good reasonable policies to me (notably, PascalCase adjectives for trait names, and `uses` after `extends`). We'll need to make sure this is agreed-upon as the good way to do it before merging, though Document behavior of static variables in traits [no ci] Document behavior of casting to traits
|
|
||
| func _ready(): | ||
| # Will work | ||
| print(HasStatic.static_var) |
There was a problem hiding this comment.
As traits are implemented it will not. Consider traits as templates that when used by a class its variables, enum, functions, signals are copied over.
There was a problem hiding this comment.
Thanks for noting this! I'm hoping to update the documentation later today to match the intended behavior 😄
| .. note:: | ||
| Godot 4.x introduces `traits <Traits_>`_ to GDScript, which may cover many of | ||
| the use cases for multiple inheritance. See their section for more information | ||
| about how they work. | ||
|
|
There was a problem hiding this comment.
Personally, I would not put this in a note, but rather include it in the preceding paragraph:
| .. note:: | |
| Godot 4.x introduces `traits <Traits_>`_ to GDScript, which may cover many of | |
| the use cases for multiple inheritance. See their section for more information | |
| about how they work. | |
| Multiple inheritance is not allowed, but Godot does support `traits <Traits_>`_, which cover many of the same use cases. |
If we keep the note, I would suggest phrasing like this, so that it reads better in much later future versions. Present tense "introduces" will feel out of date at some point.
| .. note:: | |
| Godot 4.x introduces `traits <Traits_>`_ to GDScript, which may cover many of | |
| the use cases for multiple inheritance. See their section for more information | |
| about how they work. | |
| .. note:: | |
| Since Godot 4.x, GDScript supports `traits <Traits_>`_, which may cover many of | |
| the use cases for multiple inheritance. See their section for more information | |
| about how they work. | |
I might move the "Since Godot 4.x..." to the actual traits section instead, though, in combination with the first suggestion here.
| Traits are collections of behaviors and attributes that classes can use to guarantee | ||
| functionality to themselves and other objects that may be attempting to use them. |
There was a problem hiding this comment.
| Traits are collections of behaviors and attributes that classes can use to guarantee | |
| functionality to themselves and other objects that may be attempting to use them. | |
| Since Godot 4.x, GDScript supports traits, which are collections of behaviors and attributes | |
| that classes can use to guarantee | |
| functionality to themselves and other objects that may be attempting to use them. |
If we're doing a "Since Godot 4.x" introduction (which I personally somewhat dislike, but they are common in the docs), here is a better place than the note, IMO.
| From inside a class/trait, you can access static variables from any function, both static and non-static. | ||
| From outside the class/trait, you can access static variables using the class/trait or an instance |
There was a problem hiding this comment.
| From inside a class/trait, you can access static variables from any function, both static and non-static. | |
| From outside the class/trait, you can access static variables using the class/trait or an instance | |
| From inside a class or trait, you can access static variables from any function, both static and non-static. | |
| From outside the class or trait, you can access static variables using the class/trait or an instance |
Style nitpick, using "/" in the body of the page is usually less readable IMO
Closes #10388
The trait system for GDScript being worked on at godotengine/godot#97657 appears to be mostly done, but "Write Documentation" is one of the items still unchecked. The main Godot repository only contains the class reference, which isn't especially applicable to a new language feature.
I think it'll be important for the success of this feature to prepare the user manual to describe traits, so that as soon as they're available in a stable release, users can read about them and understand how to use them.
To Do
traittrait_nameusesisSuper-final To Do
useskeyword is correctNote
These are all of the spots within the user manual I've been able to find so far, where I think making modifications to accommodate traits would be important, but of course I may have missed something. If you think of another location in the user manual that would need to be updated to acknowledge traits, please point it out and I'll add it to the list!