Can we have C# Api Docs at docs.godotengine.org?

[JupiterRider]

There are Tools to generate HTML from C# Code. One of these tools is for example DocFX: https://github.com/dotnet/docfx

Can we have this at the Godot Page to Provide C# Api Docs as well? Currently there is GDScript only: https://docs.godotengine.org/en/stable/classes/index.html

@paulloz has provided something: https://paulloz.github.io/godot-csharp-api/3.5/Godot.html https://github.com/paulloz/godot-csharp-api/

[Calinou]

I don't think we should make a dedicated build of the class reference only for C#. Instead, I'd perform live conversion of snake_case syntax to PascalCase using JavaScript: https://github.com/godotengine/godot-docs/pull/4406

[paulloz]

I don't think we should make a dedicated build of the class reference only for C#. Instead, I'd perform live conversion of snake_case syntax to PascalCase using JavaScript: #4406

That solution won't cover 100% of the C# API tho. Parts of it aren't just case conversion.
FWIW I spent a decent amount of time speaking to people here and there (whether on GH, Twitter, Discord and Rocket) about how we could bring a decent C# doc to the userbase, and it never went anywhere. Probably partly on me for getting tired of it not going anywhere and stopping to push for it.

[YuriSizov]

That solution won't cover 100% of the C# API tho. Parts of it aren't just case conversion.

I think this speaks to the idea of having a separate document, if that's needed. Wherever 2nd and 3rd party languages don't map to the engine API it would be very hard to provide the same level of coverage and quality without duplicating everything.

That said, the class reference is not language specific, it's a mirror of the engine API itself. GDScript happens to use that API without any transformations, and C# happens to have different conventions than our ClassDB. We already provide examples in both languages in the docs. For the purpose of lookup, we can rely on the conversion and maybe on the keyword system that we've been discussing for the class reference.

[paulloz]

Wherever 2nd and 3rd party languages don't map to the engine API it would be very hard to provide the same level of coverage and quality without duplicating everything.

Well, that's then the same discussion as ever. Where do we put C# on the "this is unofficial" to "this is official" line. It's not an easy thing to explain to most newcomers who get in because C# is part of the official communication and at the same time they can't find a basic classdoc reflecting the API.

Of course, nobody expects the official docs to serve documentation for a 2nd or 3rd party language. Those languages have the opportunity to serve their own anyway (an example amongst others: https://docs.rs/gdnative/latest/gdnative/). We (meaning: the C# community) don't have that luxury, because the docs for C# are expected to be hosted by the official website. The best we can do is provide an alternative option, on custom domains. Which mean without any visibility.

I agree, though, that the translation thing would be better than having nothing.

[YuriSizov]

Well, that's then the same discussion as ever. Where do we put C# on the "this is unofficial" to "this is official" line. It's not an easy thing to explain to most newcomers who get in because C# is part of the official communication and at the same time they can't find a basic classdoc reflecting the API.

I think it's more of a "hard to document several different programming languages" together. We're experiencing the same issue with the idea of adding C++ examples to the getting started set of articles. C++ is just so different to write, it doesn't map on the same flow of the existing articles. Making articles more flexible would probably result in making them less cohesive. But at the same time we just don't have the capacity to maintain two sets of articles for the same basic idea. Thus we prefer to assume that those who would want to use C++ are experienced enough to figure out how to adapt GDScript/C# examples with all the necessary paraphernalia.

Same is true for C#, to a lesser degree. And while we can more or less have the same tutorials for C#, making a split class reference is a difficult task to figure out. I think we could semi-manually handle it in some way, for the shared API rely on the automatic translation with some possible hardcoded hinting in XMLs. But if something should be done in C# in a completely different manner, then I don't know. We document those things in the descriptions these days, but how would you make them discoverable? There is the "differences" article, but you kind of have to memorize it.

btw we have been discussing linking it at the top of the built-in class reference if you're using a mono build. So those discrepancies are easier to discover.

---

Of course, nobody expects the official docs to serve documentation for a 2nd or 3rd party language.

I kind of implied that C# is a 2nd party language, because while we support it officially, we have little control over conventions and sensibilities. Not like we have with GDScript or even C++.

[paulloz]

But if something should be done in C# in a completely different manner, then I don't know.

I'm not even talking about paradigm differences or stuff you'd implement differently. Some simple stuff where you'd use a class reference are basically impossible to find: almost every flag and enum, a vast majority of what's under GD., etc.

I don't want to monopolize the conversation, so I'll back off and let others fill in.

[qaptoR]

Thus we prefer to assume that those who would want to use C++ are experienced enough to figure out how to adapt GDScript/C# examples with all the necessary paraphernalia.

Great sentiment. Because a well defined off ramp documentation from the gdscript highway to GDNative (and hopefully updated for GDExtension) and C# exists, then I think it's really already a job well done. And maybe the real next step is communicating clearly to those communities how they ought to frame their own expectations so they align better with the project.

Granted, I am biased by my prior knowledge of C++ and C# fundamentals. But I do feel that even during my formative learning in those areas such off-ramp documentation would have been adequate and suitable for my needs. I should also clarify that I have not yet dabbled in C# or GDNative, but that is not for lack of clarity in their documentation (though admittedly I have also not read it thoroughly). Rather it is due to how well developed GDScript is.

[van800]

In the Rider plugin for Godot, I would love to provide links to the api documentation. Unfortunately, currently there is no such place. It could have been similar to what Rider provides for Unity api

[Paweth]

It would be great if there was api reference for C# classes. GDscript may be fine but C# has huge existing ecosystem and is usable also outside of Godot. Having to remember all the rules how to transition from GDscript code to C# is counter productive. Not to mention that to do that one has to spend some time on learning GDscript in the first place! Developers shouldn't have to remember unnecessary things like eg. naming convention differences - they should just have place for lookups for functions and classes in language they write in! (like that great website that @paulloz once made for godot 3.4). Strange that even when there was a huge userbase exodus from Unity (where everyone was using C#), it doesn't seem like Godot team treats it with high priority. I can speak for myself only but the lack of proper C# documentation holds me back from learning Godot.