My wishlist to improve the scripting API documentation standard

Web Resources
,
1

First off, I want to say thank you for providing awesome Unity documentation! Most of it is excellent and overall I feel like the Unity manuals are more helpful than a lot of other software documentation out there. I read the docs daily and appreciate the effort.

I’d still like to suggest some improvements for the future regarding the API docs. For a simple example, let’s look at AssetDatabase.AssetPathToGUID.

At the current time, this page is telling me:

  • The function receives a parameter named ‘path’ that specifies the ‘Filesystem path for the asset’.
  • It returns a string GUID.
  • If no asset exists at path the function returns nothing.
  • All paths are relative to the project folder, e.g. “Assets/Bla.png”
  • And the example shows how to call the function.

So far, its pretty good to get started, however coming from other software development standards or when comparing to the docs of certain large japanese game developers :p, its possible to miss the following information:

  • What exactly does the function return when I pass a file path that does not exist? Does nothing mean null or empty string?
  • What if the path exists, but the asset is invalid (e.g. a ScriptableObject asset whose script name does not match the class name and therefore will return null when loaded).
  • What if I pass null or empty string?
  • What if the string I pass is too long or contains special characters that might not be supported? Will the method return or throw an exception? E.g. can I expect PathTooLongException, etc?

I’ve already sent my feedback via the Scripting API page, but this thread is a more general wishlist for more detailed information and commitment by Unity about their API. This would especially include:

  • Preconditions (e.g. what is expected to be passed exactly, does anything else need to be configured in a certain way or do I have to call other methods before calling this method)
  • Postconditions (e.g. assuming the preconditions are met, what exactly is returned or which state is modified or what side effects may be caused?)
  • What happens if any of the conditions are not met? (e.g. when my code fails to pass the correct data or when Unity fails internally)

Thank you for listening and keep up the good work!

3 Likes
2

I’d like to add another example: GetComponentsInChildren

As of today (Unity 2019.2) this page is missing a crucial overload of the function:
void GetComponentsInChildren<T>(bool includeInactive, List<T> result)

Once this missing overload is documented, I would hope for the following details:

  • What will happen if I pass null instead of a list? Will the method throw ArgumentNullException or another type of Exception that I can catch or simply ignore the call?
  • If I provide a result list which is not empty, will it be cleared for me or should I call clear myself? If it will not be cleared, will new values be appended to the end or overwrite existing values without deleting entries if the provided list is longer than the new return value.

Additionally, I believe that the existing description of the return value for the other overload can be improved. It currently states:

Returns T[ ] A list of all found components matching the specified type.

  • The method returns an array, not a list.
  • Is the array empty or null if nothing was found? (We know by convention that Unity always returns an empty array, but I still think it should be documented everywhere so beginners can easily understand what to expect).
  • Is the array guaranteed to only contain valid component references or is a null entry possible? For example, if an added MonoBehaviour script is renamed or deleted, I believe that null entries are put into the array, because the script is on the GameObject but cannot be loaded.

There’s also an overload of the method which takes a parameter System.Type to specify the component type. Again:

  • What if I pass a type that does not derive from Component? Exception or empty array?
  • What if I pass null?