The Netcode API documentation needs better styling!

The API reference is pretty hard to scan and pretty much a chore to use as of now simply because there was no effort spent on making it readable. While a lot of information may be in there, it is just too cumbersome to use the API reference, especially when trying to just glance over the contents of a class to see what it has to offer.

The most pressing issues:

Overall, there's way too much vertical space added for each line, requiring a lot of scrolling. Line height should be condensed and the relative font sizes need adjustment. Specifically the names of properties/methods are hardly standing out next to the slightly smaller subsections (ie Declaration, Field Value).

The parameter (Type/Description) tables dominate visually, making them seem like headers rather than just providing method parameter information. Much of that information is useless or confusing, with for example List just being written again but as the .NET verbose FullName of the types. Similarly, the "Inherited Members" section repeats a lot .NET standard base types / interfaces.

Lastly, on the right-hand side you can only navigate to Fields, Properties, Methods where it should really have a list of all the methods, properties, fields and so on for quick navigation and scanning of the class' contents.

Just on the off-chance that it only looks like this for me, here's what I see on the API ref pages (note: you're essentially just looking at the class description and two fields here!):

8472848--1126064--upload_2022-9-28_16-39-6.png
...
8472848--1126061--upload_2022-9-28_16-36-46.png

2 Likes

@CodeSmile thanks for the feedback, yeah the API ref has long needed a cleaner presentation. I'll share this internally with the docs team, as I am not clear if they plan to look into it in the near future.

Are the API docs open source per chance?

Yeah, what is published on the site is editable, and you can also access the GitHub repo: https://github.com/Unity-Technologies/com.unity.multiplayer.docs/tree/main/docs/api

Thanks! There's another important issue: nothing is hyperlinked. So one class may have references to other classes but none of it can be used to navigate the API reference like you can do in practically any other API reference.