C#: Finish documentation of GodotSharp public API

[Repiteo]

This PR is exclusively aimed at documentation, so absolutely no code changes were made. The sole exception is GodotSharp.csproj with the removal of <NoWarn>CS1591</NoWarn>, as it now has an accompanying docstring for every single public API.

It's entirely possible that some parts of the documentation aren't fully representative of their implementation, as the catch-22 of this scenario was a lack of documentation to know what to document. In addition, many sections were implemented through automation; while I tried my best to double-check for any potential discrepancies, it's entirely possible some still slipped through the cracks. Nonetheless, I'm largely confident in what's in place now & making adjustments at this stage will be significantly easier.

[Repiteo]

Implemented a few new fixes, most to the initial commits but a handful to existing docstrings. These include:

• Fixing some erroneous paramref syntax (see paramref to paramref name) Migrated to Fix issues in C# documentation comments #79748
• Ensured language keywords use langword and not cref
• Resolved ambiguous functions by assigning real_t (originally part of C#: Fix MSVC dotnet builds failing if running dev_mode #79351) Migrated to Fix issues in C# documentation comments #79748

Every change remains strictly documentation

[RedworkDE]

Implemented a few new fixes, most to the initial commits but a handful to existing docstrings. These include:

I would suggest separating these fixes into a new PR, as some of the new documentation will probably need a lot of discussion and some of these bits (at least everything in the Bridge namespace) are not even really supposed to used, except by the engine.

[Repiteo]

I would suggest separating these fixes into a new PR, as some of the new documentation will probably need a lot of discussion

Done! Those bits were moved to #79748

and some of these bits (at least everything in the Bridge namespace) are not even really supposed to used, except by the engine.

Strange then that CS1591 would consider all of those "public". In either case, assuming the Nowarn will still be removed at some point, would it be better to instead have the GodotSharp .editorconfig handle more specific cases? eg:

[**/Bridge/**.cs]
# Missing XML comment for publicly visible type or member
dotnet_diagnostic.CS1591.severity = none

[raulsntos]

Thanks for contributing to the .NET documentation. There's a lot here so this is only a partial review.

A lot of these are not very useful since they just state the obvious. Just adding documentation to get rid of the warning is not good enough IMO. I think it's better to keep an API undocumented than document it poorly, because there's no warning for poor documentation.

You said you automated some of these. That's a bit of a red flag. I would encourage you to remove the documentation that you are not sure of. There's no need to document the entire API all at once, how about changing this PR to document only some things? And then we can leave the rest for a future PR? For example, I would recommend to leave out the documentation for Bridge and NativeInterop since those are internal APIs meant to be used by the engine and it's likely difficult for contributors to document them.

Also, it's important to me that the documentation is consistent. This means we should use the same phrasing/wording for similar APIs. For example, take a look at the Equals method in any of the C# structs (i.e. Vector2) and you'll see that we usually use the same style, but the documentation for NodePath.Equals is very different from that. We also try to keep the documentation somewhat consistent with Core.

[raulsntos]

I don't think these descriptions are very useful, perhaps we should just disable the warning for these delegates?

[raulsntos]

What do you mean by "handle a dotnet hot-reload environment"? This struct just contains function pointers that are retrieved by the engine so it can call the C# methods from C++.

[raulsntos]

I don't think these documentations are useful and would be very difficult to maintain. I guess it's unlikely these values will change, but it has happened before so it's not impossible. I think it'd be better to disable the warning here, like we were doing before with the #pragma.

[raulsntos]

I left these Quaternion methods (exp, get_angle, get_axis and log) undocumented because they are undocumented in Core as well. They should be documented in Core and the C# documentation should be in sync with that.

godot/doc/classes/Quaternion.xml

Lines 79 to 83 in 851bc64

	<method name="exp" qualifiers="const">
	<return type="Quaternion" />
	<description>
	</description>
	</method>

If you want to document these methods I would recommend to open a new PR that focuses entirely on these methods and documents them for Core too.

[raulsntos]

You forgot to undo this change. See #79748 (comment).

[Repiteo]

Very, very good points raised all around. In particular, I didn't realize just how synced a lot of the existing documentation was to existing implementations and, more importantly, the core itself. That, alongside the realization that many of these areas are meant only for internal use, made a good chunk of this PR a misguided effort

Closing in favor of multiple, more focused PRs at some later point. I'd rather have fresh starts than try to retrofit something of this scope