Let's get this out of the way: Unity docs are atrocious.

Seriously, I can't believe Unity lasted this long with documentation so lackluster, so half-assed, so incomplete. At least it's not as bad as Unreal's documentation though, but that's a story for another day.

The current mess

To show exactly what I mean, consider the documentation for the generic version of GetComponent right up until 2020.3:

Now, admittedly, this is outdated. Today, there's actually a helpful description in its stead:

But I still have gripes with this though. Namely, the signature is incorrect. T isn't an inherited parameter from the declaring class, it's distinct to this method, so the correct signature is as follows:

public T GetComponent<T>();

You can't just ignore generic type parameters, Unity, god damn.

It doesn't end there though. The signatures for many of the members in various types are just blatantly wrong. Consider the position property of the Transform class:

Because of how this declaration is written, if you didn't know any better, you'd be led to believe this is a field. After all, this is the syntax for declaring a field. You have the visibility modifier, the type, followed by the name, and terminated with a semicolon.

But no, you're wrong. This is in fact a property. The correct syntax that should be written here is:

public Vector3 position { get; set; }

And I mean, you could optionally include the extern keyword as this property does call into native code since the majority of the Unity engine is native, but honestly that's irrelevant to the caller. The fact of the matter is, position is a property that has both a get and a set accessor, both public, and so yes it kind of behaves like a public field - but it isn't one. And that's an important distinction to make.

You know what's worse though? You know what really grinds my gears?

Head to the docs for UnityEngine.Vector3. Go on, I dare you. I'll wait.

Did you notice it? No?

Here I'll show you:

The x, y, and z members are grouped under “Properties”. THEY ARE NOT PROPERTIES.

THEY ARE FIELDS.

WHY DOES UNITY CLAIM PROPERTIES ARE FIELDS, AND FIELDS ARE PROPERTIES?

Oh but it gets worse. Let's mention the fact that a lot of the Unity docs fail to mention very important details. Like how Debug.Log accepts an object which means any value types you pass to it get boxed.

Yes, seriously.

Even something as innocuous as Debug.Log(42), will box 42 creating an allocation. But wait, there's more! ToString() is then called to produce a string representation of the object which creates another allocation. So congratulations. Whenever you simply log player health or player score, you're killing performance by not just calling ToString() yourself (or using an interpolated string, whatever floats your boat.)

There's a reason Console.WriteLine has so many overloads accepting so many types. All built-in numeric types get special overloads, to prevent boxing. The object overload is a last-resort:

This is just one of the many important details that Unity fails to notify its developers of. I could be here for hours. But I'd rather move on.

There's hope yet!

I don't think it's unreasonable of me to say that Microsoft are the kings of excellent documentation. Microsoft Learn (formerly Microsoft Docs, formerly formerly MSDN) is so well made, in my opinion it sets the bar of how docs should be written.

I once created a proof-of-concept design, showcasing how Unity docs could be good, by using a style heavily inspired by Microsoft Learn.

How did I accomplish this?

To be honest, it was a massive hack. I created a Class Library project named UnityEngine.CoreModule (so the assembly name could be displayed as that), and began writing out the boilerplate of all the types and members that Unity has to offer. I wrote xmldoc for it all, and used docfx to generate documentation files from the source xmldoc.

However, the front-end was a custom ASP.NET Core app. I didn't use docfx to present a static doc page, as you might have expected. I had my custom front-end read the intermediate format provided by docfx coupled with a metric fuck ton of custom CSS for the styling, and topping it off with HighlightJS to render codeblocks for the type and member signatures.

I soon realised, however, that this would be a mammoth task to do. Rewriting the entire Unity assemblies just to get documentation is a waste of my time.

Ditching DocFX

I knew if I were to succeed in making Unity docs not suck, I'd have to come up with a more efficient pipeline.

So, for a little while now I've been working on a tool which can generate the declaration syntax for any type or member. In essence, I'm writing a tool to provide me this string:

You'd be surprised at how few tools exist to actually do this. So I wrote one, and it's open source.

But I didn't stop at C#, oh no. The tool also supports VB.NET, F#, IL and C++/CLI. Why? Because the Microsoft docs allow you to view the declaration syntax (and example snippets), in any of these languages:

If you look at the signature for Console.WriteLine(string), for example, you'll see this:

But change the language to C++/CLI, or VB.NET, and you'll see the syntax change:

Now your immediate question might be, “why would I need the syntax for Unity types in languages other than C#? Doesn't Unity only support C#?”

Kind of. It's true, Unity is only bundled with a C# compiler. Code written inside the project can only be C# and you'd be forgiven for thinking that's all you can use.

But forget not, Unity hosts the .NET runtime (specifically, a fork of Mono as of the time of this post) to actually execute your compiled code. This means you can use any .NET language that compiles to IL.

F#, VB.NET, C++/CLI, hell you could use IronPython if you wanted. As long as you prebuild the code to a .NET .dll, you can place that .dll into your Assets as just another library. You can technically write your game in any .NET language if you so desired. It's not common to do, but it's possible and there's nothing stopping you from doing it.

So anyway, the tool I wrote supports these major .NET languages. For example, take a look at the declaration syntax for one of the GameObject constructors:

And the correct syntax for Transform.position:

Epilogue

Once this syntax generator is working correctly for all languages, I'll be utilising it along with an assembly scraper to extract every single type, and all of its members, from my Unity install directory; to generate the documentation files needed for the front-end to eventually read and display just like my proof-of-concept. Fortunately, the brunt of the Unity docs is available in offline files too, in the Unity install directory, placed conveniently alongside the assemblies. I can use this as a starting point, and begin to rewrite the parts that need rewriting over time.

Once I have a very basic version of the front-end up and running, I'll be deploying it to my VPS and hosting it for the public for the foreseeable future. It will also be 100% open source when that time comes, so I will accept anyone coming in and contributing to making better Unity docs. I know I cannot do this by myself. It would be foolish of me to assume otherwise. But I also know I'm not the only one who wants to do this, and I'll take all the help I can get. And of course, I'll be writing more blog posts as I make progress on this project. So stay tuned.

Unity has the potential to be such a great engine. It has the potential to be a positive development experience, as it's one of the very few capable engines out there for C# / .NET. Let's make the docs what they should be, what they deserve to be, for everyone's sake.

To Unity: if you want to hire me for this, I'll await your email.