Search Unity

  1. Unity 6 Preview is now available. To find out what's new, have a look at our Unity 6 Preview blog post.
    Dismiss Notice
  2. Unity is excited to announce that we will be collaborating with TheXPlace for a summer game jam from June 13 - June 19. Learn more.
    Dismiss Notice

The documentation is overall quite poor

Discussion in 'Documentation' started by Sabo, Dec 23, 2015.

Thread Status:
Not open for further replies.
  1. Sabo

    Sabo

    Joined:
    Nov 7, 2009
    Posts:
    151
    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:

    http://docs.unity3d.com/ScriptReference/PropertyDrawer.html -> "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.

    http://docs.unity3d.com/ScriptReference/DragAndDrop.html
    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, http://forum.unity3d.com/threads/ed...stem-needs-to-be-initialized-by-unity.219342/ -> "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. Dantus

    Dantus

    Joined:
    Oct 21, 2009
    Posts:
    5,667
    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:
    http://blogs.unity3d.com/2015/12/22/going-deep-with-imgui-and-editor-customization/

    This would have been invaluable for me two years ago :)
     
  3. hippocoder

    hippocoder

    Digital Ape

    Joined:
    Apr 11, 2010
    Posts:
    29,723
    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. michael-bartnett

    michael-bartnett

    Joined:
    Jul 8, 2012
    Posts:
    8
    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?

    http://docs.unity3d.com/ScriptReference/GeometryUtility.CalculateFrustumPlanes.html

    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?

    http://docs.unity3d.com/ScriptReference/RectTransform.GetWorldCorners.html

    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 :p

    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. Graham-Dunnett

    Graham-Dunnett

    Administrator

    Joined:
    Jun 2, 2009
    Posts:
    4,287
    The docs team is growing in 2016, with the intention of making the documentation better.
     
    Sabo and Dantus like this.
Thread Status:
Not open for further replies.