Crappy documentation all over - Please Contribute!

Since the documentation needs focus (always has), I've decided to start a post where I will try to keep posting references to various issues and complaining until something is done. Our ability to do advanced work with unity depends on our ability to parse how it's API works, and in many cases the documentation hamstrings my ability to do so.

First entry:
https://docs.unity3d.com/ScriptReference/SerializedObject.ApplyModifiedProperties.html

If your documentation basically consistes of the method name slightly reordered, you might be a lazy document writer. Unity has a team large enough to create something like UnityConnect (an utter failure, but undoubtedly requiring quite a large investment) but don't document the "under the hood" workings of public APIs in the docus.

Coder Sin Level: 7/10 Laziness gives high marks on this one. Just one example of many.

 

https://docs.unity3d.com/ScriptReference/SerializedObject.Update.html

I had to find a unity answers entry for this one explaining that the SerializedObject acts almost as a shadowed copy of the object it targets, and that if the object changes, we have to pull it's state into the SerializedObject. I assume this is correct, but is it? Who knows!

Unity's documentation needs to explain things fully.

I propose the documentation be converted into a wiki where we as a community can take our collective knowledge and update missing or flawed information therein.

 

And now: http://enemyhideout.com/2016/03/unity-tip-advanced-serializedproperties/

That's a link to an article way back in the start of 2016 pointing out that the documentation is lacking for the SerializedProperty.Next() method. Lets take a look at that page now.

https://docs.unity3d.com/ScriptReference/SerializedProperty.Next.html

"Move to next property." - Wow, thanks for that clarification.

Considering how the behavior of serialize properties are somewhat unintuitive, this seems like a big oversight. Please fix this.

 

I can recommend this extension, as it gives the ability to add user comments to the docs. It's not very widely used, but I hope it picks up steam.

SerializedObject/Property is a really funky interface, with it's own idiosyncrasies. A serialized property is both a representation of a single, serialized data point in one to many objects, and an iterator over properties.

It's very complex, pretty powerful, and has documentation that assumes that you know all of it's internal jargon. Which you obviously don't. So, yup, it needs some proper rework.

 

@Baste Thanks for the comment on the extension. I'll check it out.

Edit: I think it's better than nothing. I'll have to explore how to just browse generated user content. It could help if unity would at least add a note somewhere on each page promoting it's use for now.

The long term solution has to be reworking the docs system for the userbase to contribute to enhancing/maintaining, however. My question is, why is this now and always been a low priority concern for the unity team?

Edit 2: I'd also wonder if the team of people at unity who maintain documentation would be using that chrome extension, if not then it's not going to be the cooperative effort we need.

 

https://docs.unity3d.com/ScriptReference/UI.InputField-onEndEdit.html

Here we see the onEndEdit callback being used in a somewhat confusing manor, they supply a delegate as a listener and then pass in the reference of an inputfield which is stored in the class. If we were wondering about the actual signature of onEndEdit, we might look at the following:

https://docs.unity3d.com/ScriptReference/UI.InputField.SubmitEvent.html

"Unity Event with a inputfield as a param."

This isn't actually the case, if we dig into SubmitEvent we see the following:

Code (CSharp):

1. public class SubmitEvent : UnityEvent<string>

So in summary, the example use of onEndEdit is bad to begin with as it doesn't actually show usage of the callback with it's actual signature in mind. If we explore SubmitEvent, we find out that the documentation for it is incorrect.

Unless I'm missing something, that seems like a couple major issues in using this, especially if you were newer and needed a very direct example of the usage where a string is being returned to the listener when onEndEdit fires.

Coder Sin Level: 8/10 - This would get a higher level, but at least effort was given with a code example. However in the one hand we have a bad example usage and then actual invalid information in the other hand. Not good.