Search Unity

  1. Unity 2019.2 is now released.
    Dismiss Notice

Feedback My wishlist to improve the scripting API documentation standard

Discussion in 'Documentation' started by Xarbrough, Sep 26, 2019.

  1. Xarbrough

    Xarbrough

    Joined:
    Dec 11, 2014
    Posts:
    546
    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:

    1. 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)
    2. Postconditions (e.g. assuming the preconditions are met, what exactly is returned or which state is modified or what side effects may be caused?)
    3. 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!
     
    brunocoimbra and JoNax97 like this.