C#: Requirement of `partial` is not explained or documented

[cai-tan]

Your Godot version: v4.1.1.stable.mono.official [bd6af8e0e] Issue description: Currently, if partial is omitted from a Node-inherited class definition, it does emit the error GD0001: Missing partial modifier on declaration of type 'PlayerControllerState' which is a subclass of 'Godot.GodotObject'. However, nothing in the documentation explains why this is, or even alerts the user that partial is required when making a Node script. I ended up finding the reasoning in a blog post that I only found through a link on the (currently defunct) Godot ask site. URL to the documentation page: https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_basics.html If you know how to fix the issue you are reporting please consider opening a pull request. We provide a tutorial on using git here: https://docs.godotengine.org/en/stable/community/contributing/pr_workflow.html, writing documentation at https://docs.godotengine.org/en/stable/community/contributing/docs_writing_guidelines.html and contributing to the class reference here: https://docs.godotengine.org/en/stable/community/contributing/updating_the_class_reference.html

[AThousandShips]

The page on C# is not intended as a tutorial on C# in general, you are expected to have a grasp of it already, as per this note:

This is not a full-scale tutorial on the C# language as a whole. If you aren't already familiar with its syntax or features, see the Microsoft C# guide or look for a suitable introduction elsewhere.

[cai-tan]

I have a grasp of C# already, enough to know that classes don't normally require a partial modifier.

On Wed, Sep 20, 2023, 03:17 A Thousand Ships @.***> wrote:

The page on C# is not intended as a tutorial on C# in general, you are expected to have a grasp of it already, as per this note:

This is not a full-scale tutorial on the C# language as a whole. If you aren't already familiar with its syntax or features, see the Microsoft C# guide https://docs.microsoft.com/en-us/dotnet/csharp/index or look for a suitable introduction elsewhere.

— Reply to this email directly, view it on GitHub https://github.com/godotengine/godot-docs/issues/7965#issuecomment-1727316533, or unsubscribe https://github.com/notifications/unsubscribe-auth/AT55MQEJP2N6AYQBNDOVTALX3KYDHANCNFSM6AAAAAA47JOUQE . You are receiving this because you authored the thread.Message ID: @.***>

[raulsntos]

The partial modifier is a C# feature commonly associated with C# source generators, there's nothing specific to Godot about it. Source generators require classes being partial so that code can be added to them on generation, that's just how source generators work, in case you're not familiar with them you can read more about them in Microsoft's Source Generators documentation page.

In 4.2, we also have documentation pages for every diagnostic. In these pages we can go in more detail about what causes the error, and what can be done to fix it. Take a look at the documentation page for the GD0001 diagnostic.

There's also a PR that adds a link to these documentation pages in the diagnostic itself, this allows your IDE to show you the link making this documentation more discoverable.

• https://github.com/godotengine/godot/pull/80489

[cai-tan]

Source generators are still uncommon enough for it to take experienced C# devs off guard. The addition of a page explaining GD0001 is good, but there isn't a single line in the existing documentation outside of that even denoting it's using a source generator at all. Not specifying that Godot uses source generators because "you should have a grasp of C#" is like not telling someone what kind of fuel a hauler truck takes because "you should have a grasp of trucking".

I get that the documentation isn't supposed to provide a general tutorial of C#, but exactly how general is this? This might make perfect sense to the engine developers who know they just shipped an update changing from reflection to source generation, but not everyone developing with Godot is hardwired to the same information feed. Most projects (namely Unity!) are using reflection. Most devs will expect reflection.

On Wed, Sep 20, 2023, 06:53 Raul Santos @.***> wrote:

The partial modifier is a C# feature commonly associated with C# source generators, there's nothing specific to Godot about it. Source generators require classes being partial so that code can be added to them on generation, that's just how source generators work, in case you're not familiar with them you can read more about them in Microsoft's Source Generators https://learn.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview documentation page.

In 4.2, we also have documentation pages for every diagnostic. In these pages we can go in more detail about what causes the error, and what can be done to fix it. Take a look at the documentation page for the GD0001 https://docs.godotengine.org/en/latest/tutorials/scripting/c_sharp/diagnostics/GD0001.html diagnostic.

There's also a PR that adds a link to these documentation pages in the diagnostic itself, this allows your IDE to show you the link making this documentation more discoverable.

• godotengine/godot#80489 https://github.com/godotengine/godot/pull/80489

— Reply to this email directly, view it on GitHub https://github.com/godotengine/godot-docs/issues/7965#issuecomment-1727669307, or unsubscribe https://github.com/notifications/unsubscribe-auth/AT55MQBDAPTA7LG2RM4MIH3X3LRNVANCNFSM6AAAAAA47JOUQE . You are receiving this because you authored the thread.Message ID: @.***>

[AThousandShips]

This might make perfect sense to the engine developers who know they just shipped an update changing from reflection to source generation

When was this changed? AFAIK source generators has been used for C# in Godot for a long time?

[paulloz]

When was this changed? AFAIK source generators has been used for C# in Godot for a long time?

Basically since 4.x, very early on in the 4 dev cycle.

FWIW, although it is absolutely not necessary to know anything about generators (nor why classes need to be partial) to use Godot, the "why do I need to write partial?" comes up often enough for us to have pinned a link to this news in the Discord help channel for C#. Maybe a quick reference of the sort would be warranted in the docs as well.

[doctorseus]

Yes, not sure why the focus is on whatever the documentation should include a section about what partial does. It`s a language feature which is not even relevant to the user.

However, what should certainly be part of the documentation is that Godot requires a class to have a partial modifier and why (it uses source generators). Because the reason why a class has to have it is purely because as of how Godot works. IMHO

[Nortmorn]

Agreed with the issue. I worked with Unity for about 5 years and then switched to Godot and never knew about partial classes and source generators, this is not a common thing to know. And suggestions to get "a grasp" of the language first are pretty snobbish. Using this logic we dont need docs at all, just read damn source code/comments and look at constant/function/class names, it should be enough for you to understand how it works and what it does.