Feedback Documentation for SaveFilePanelInProject is lacking

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.

 

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.