Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add manual pages and content for upcoming GDScript trait system #10393

Draft
wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

Add manual pages and content for upcoming GDScript trait system #10393

wants to merge 3 commits into from

Conversation

Meorge
Copy link

@Meorge Meorge commented Dec 9, 2024 •
edited
Loading

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

  • GDScript basics
    • Example of GDScript
      • Trait usage
      • Show abstract methods being implemented
      • Show concrete methods from trait being called(?)
    • Keywords
      • trait
      • trait_name
      • uses
      • is
    • Variables - Valid types should include traits
    • Typed arrays - Valid types should include traits
    • Static variables - Should clarify behavior of a static variable within a trait?
      • Tested - static variable belongs to the trait itself, and is not inherited by the using class
    • Casting - Should clarify behavior of casting to a trait?
    • Functions - "Functions always belong to a class" is no longer valid, as they can (more or less?) belong to a trait instead
    • Classes > Inheritance - "Multiple inheritance is not allowed" should have a note added to it saying that's somewhat what traits are for
    • Add new section on Traits, mimicking a lot of the Classes section
  • GDScript style guide
    • Add naming conventions for traits
    • Code order - Add traits
    • Class declaration - Add traits
  • Static typing in GDScript
    • What can be a type hint - Add traits
  • (Possibly) Introduction to traits
    • Because this will be a big new concept, it may be good to have a "tutorial" page that explains what traits are, why they're useful, and how to use them.

Super-final To Do

  • Confirm naming conventions are agreed upon
  • Confirm uses keyword is correct
  • Confirm all instances of "4.x" are replaced with whatever Godot version this feature is being added in

Note

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!

This was referenced Dec 8, 2024
Open
Open
@AThousandShips AThousandShips added enhancement area:manual Issues and PRs related to the Manual/Tutorials section of the documentation waiting on PR merge PR's that can't be merged until a engine PR is merged first labels Dec 9, 2024
@Meorge
Add documentation for traits to relevant pages
29ec0d2 
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
tetrapod00
tetrapod00 reviewed Dec 11, 2024
View reviewed changes
Copy link
Contributor

@tetrapod00 tetrapod00 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple things I noticed. Since this is a draft and the PR is not yet approved, there is no rush to apply these changes.

tutorials/scripting/gdscript/gdscript_basics.rst Outdated Show resolved Hide resolved
tutorials/scripting/gdscript/gdscript_basics.rst Outdated Show resolved Hide resolved
tutorials/scripting/gdscript/gdscript_basics.rst Outdated Show resolved Hide resolved
@tetrapod00
Copy link
Contributor

This documentation seems complete enough without an intro to traits page, actually. So I think that can be safely deferred to a future PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@tetrapod00 tetrapod00 tetrapod00 left review comments

@SeremTitus SeremTitus SeremTitus left review comments

Assignees
No one assigned
Labels
area:manual Issues and PRs related to the Manual/Tutorials section of the documentation enhancement topic:gdscript waiting on PR merge PR's that can't be merged until a engine PR is merged first
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Add manual pages and content for upcoming GDScript trait system
4 participants
@Meorge @tetrapod00 @SeremTitus @AThousandShips