Search Unity

  1. We are migrating the Unity Forums to Unity Discussions. On July 12, the Unity Forums will become read-only.

    Please, do not make any changes to your username or email addresses at id.unity.com during this transition time.

    It's still possible to reply to existing private message conversations during the migration, but any new replies you post will be missing after the main migration is complete. We'll do our best to migrate these messages in a follow-up step.

    On July 15, Unity Discussions will become read-only until July 18, when the new design and the migrated forum contents will go live.


    Read our full announcement for more information and let us know if you have any questions.

Feedback Documentation for SaveFilePanelInProject is lacking

Discussion in 'Documentation' started by Xarbrough, Feb 18, 2021.

  1. Xarbrough

    Xarbrough

    Joined:
    Dec 11, 2014
    Posts:
    1,188
    Hi, thanks for constantly improving the docs. I'd like to make them even better and suggest adding more information to the individual parameters and the overall expected behavior in functions such as EditorUtility.SaveFilePanelInProject.

    At first glance, this doc page is alright. It has a description and an example, however, I repeatedly have to resort to "trying things out", which costs time and feels unprofessional. Even after years of experience, I can't remember how exactly these things work in detail and it would be immensely helpful to just have it documented right on the XML docs in code, without even having to open the online documentation.

    Here are some questions I have when looking at the existing documentation of this function:
    • Will the returned path be relative to the project, or relative to the Assets directory? Meaning, will it start with "Assets/"?
    • Will it always open at the root or at the last location a user browsed to?
    • Can the browsing behavior be changed by passing in a full path to the default name?
    • Does defaultName include the extension or only the name?
    • Does the extension include the dot or not? Does it matter or will it be fixed automatically?
    • Where is this "message" argument displayed? Maybe only on OSX?
    • What happens if any of the arguments provided are invalid? Will exceptions be thrown?
    • What is the return type if anything goes wrong in case of no exceptions? Empty string? When could this happen? Is there any feedback about what went wrong?
    I believe, if we would ask the dev who wrote this function, or just experimented with the inputs and outputs we could answer these questions in 30 minutes and add them as XML docs to the function. That would save each Unity dev from having to look up info on the web and do their own experiments.
     
    DaniBarca likes this.
  2. DaniBarca

    DaniBarca

    Joined:
    Apr 16, 2015
    Posts:
    4
    Found myself with some of these same questions. Bumping to give it visibility. Also:

    * There is a last optional "path" argument that doesn't appear in the docs. Is it the default directory? Or maybe it limits where the user can save the files? Is it the default path including the file name? Is it what will be returned if the user presses cancel? I see several interpretations and the name is not self-explanatory enough in this context IMO.
     
    cdr9042 likes this.