The documentation is overall quite poor

Web Resources
1

I’ve been working quite a bit on custom editor things lately, and the documentation is severly lacking. This is not only true for editor scripts, but that’s where I’ve noticed it the most since it’s where I’ve spent almost all my time recently.

Some examples:

Unity - Scripting API: PropertyDrawer → “Note that for performance reasons, EditorGUILayout functions are not usable with PropertyDrawers.”

But they do seem to work, at least for me, and based on a forum post probably for at least one other person as well.

Oh boy… this one… so many issues…

  • .objectReferences → “Never returns null. If no object references are available returns an empty array.”. Sounds good, the standard .NET way of never returning null for collections. It also hints (a lot) that it’s ok to not set that field to anything, especially since there’s a “SetGenericData” function available. This is not the case, and it was very hard to figure out why since Unity didn’t inform me in any way whatsoever. It simply stopped / never began to fire DragUpdate and/or DragPerform evernts. I was lucky enough to find a single sentence in a thread from 2013 about this issues, Editor DragAndDrop bug - system needs to be initialized by Unity? - Unity Engine - Unity Discussions → “Oh, I also set a “new object[ ] { null }” in the objectReferences fields. Maybe it has something to do with it. Sorry… 3 AM.”. A lot of hours wasted because of either a bug in how the DragAndDrop class works or due to poor documentation. Further down in the thread someone posts, “So my guess is, Unity at some point try to test or to marshal “objectReferences” and get an invalid pointer, and someone forget to throw an exception when that happen”.
  • .visualMode → “The visual indication of the drag.” Right. Except, it does more than that. Just seeing a field called “visualMode” hints (again, a lot) about the usage; get / set the visual indication used when doing a drag operation. For some reason someone thought it’d be fun to also have the .Rejected and .None modes actually affect how the DragAndDrop behaves. I can accept that (although I think the name of the field isn’t good if the field affects behaviour), since visual mode can be interpreted in a different way, but if that’s the case the documentation for the visual mode enum should state that. Clearly.
  • .SetGenericData() → Not the best of names since it doesn’t work with generic data.
  • And better examples would be nice. Maybe not needed if the issues listed is taken cared of, but hrms.

There are a lot of places where the documentation for fields and functions is “incomplete”. A typical example I found today when trying to learn about SerializedProperty. A serialized property has a function called ClearArray(). Kind of obvious what that function does, right? I mean, I’d guess that it “clears” the array, emptying it, removing all the elements from the array and so on. The description even says so in case it wasn’t obvious enough, “Remove all elements from the array.”. However, seeing such a description among the first public functions listed on a SerializedProperty (which has a ton of fields and quite a few functions) kind of doesn’t say much. Sure, it clears the array, but what array? I had to click on the function name to get to the page dedicated for the function, where I saw “See Also: isArray.”. After clicking on that link I understood “what array” it was that was being cleared when calling the function.

Now, the last part isn’t a major thing in itself, but the same issue keeps coming up over and over, and it’s often easily fixed. In this particular adding something along the line of “… when the serialized property is an array.” would’ve made it so much more clear.

There. Can’t sit around complaining to myself if I’m not trying to do something about it. Again, apart from the specific DragAndDrop stuff I’d just like an overhaul. I understand it costs time and money and all that, it’s fine. But please, do have a look at the DragAndDrop class (either the code or the documentation, because they are severly misaligned and / or not working as intended).

2

I agree that the documentation for editor scripting is lacking a lot. For the simple functionality, things are usually working as expected. But once you dive a little deeper, you are lost with undocumented parts. Even if you find them, you have to guess what that thing is doing and how it is supposed to be used. Sometimes I googled for some of the things and found the solution in a GitHub repository where someone with knowledge of the internals had some code for that part.

The best documentation I have ever found about it in general was just release two days ago:

This would have been invaluable for me two years ago :slight_smile:

3

For me, editor scripting is generally just trying things until something sort of works. I haven’t the energy to fight Unity on this or even complain so I just hope for the best tbh.

4

I frequently run into API docs that are incomplete, or only document the obviuos aspects of an API. As someone who’s been working with Unity for a while, I feel like I’m supposed to be the audience for this type of documentation, but it doesn’t really serve me that well.

It’s sort of convenient for knowing what members a class has, but I often get the same (or better) information from autocomplete or by opening UnityEngine.dll in ILSpy. What I truly need a reference for is details and inner workings of various APIs that I don’t use frequently, and the script reference doesn’t really offer that.

Here’s a couple of concrete examples:

GeometryUtility.CalculateFrustumPlanes: which plane is which in the array returned?

Docs bug filed spring last year: http://fogbugz.unity3d.com/default.asp?598028_6tqd72o3htqrtppn

This was reported on 3.5 so I can imagine that it was possibly ignored for that reason, but the version wasn’t really relevant to the issue, and it would probably be good to auto-reply to issues filed on old versions to let people know, “Hey, we ignore reports for versions < $V”.

Same genre of issue, which corner gets written to which element of the out parameter?

It’s clockwise, starting from bottom-left (I made sure to write this one down).

Serialized Object/Property: Just more documentation on this in general.

  • serializedProperty.isArray will be true when serializedProperty.propertyType == SerializedPropertyType.string
  • If you’re iterating through properties of a component, you will need to skip an initial list of Unity-internal properties (e.g. “m_ObjectHideFlags”, “m_PrefabParentObject”, “m_PrefabInternal”, “m_GameObject”, “m_Enabled”, “m_EditorHideFlags”, “m_Script”, “m_Name”, “m_EditorClassIdentifier”).
    I understand that you’d probably rather not commit to internal formats and that at sufficiently low levels of API usage it’s reasonable to expect me to do a certain amount of poke-and-test, but some remarks in the docs of SerializedProperty saying, “hey, there’s this also iterates internal things, make sure to handle that” are probably in order.

One-liner descriptions of a function call or field aren’t super valuable compared to specific details (like the return value indices mentinoed above) or larger documents giving an overview of how a set of APIs work.

Some examples of docs like this that are really valuable:

  • Aras’ recent additions to the shader docs
  • Richard Fine’s recent blog post about OnGUI that Dantus mentioned
  • The forum/blog posts that Tim C and Lucas Meijer did on serialization a few years ago
  • UnityEngine.UI Source on Bitbucket :stuck_out_tongue:

I read in another thread that there are plans to expand the docs team. Here’s hoping that it will result in documentation aimed at more advanced devs who already mostly grok a particular topic, but need to know Unity’s quirks and the tradeoffs made for its implementation.

5

The docs team is growing in 2016, with the intention of making the documentation better.

2 Likes