Exceptions and docs

With the increase in chatter about exceptions with the upcoming release of API 2.0 I took a deeper look into the docs.

I might be missing something obvious but how is there no prominent list in the documentation for the exceptions related to each doc entry?

For example, and there are other occurances: http://documentation.xojo.com/api/graphics/font.html The Font method is index based, if you were a newcomer to Xojo stumbled upon that page, how would you know that an http://documentation.xojo.com/api/exceptions/outofboundsexception.html can even be raised by using that method? Are there any other exceptions that I should be concerned about?

In the doc page for http://documentation.xojo.com/api/exceptions/outofmemoryexception.html I see a comment like “This exception is mostly useful with MemoryBlock and Picture”, but it doesn’t mention what else its useful for.

Another reason I looked into this was a conversation on Discord. There was a problem with a piece of code in windows that threw an odd exception (this is the simplified test sample not the live code so don’t waste time pointing out the issue :)):

Dim p As New Picture(50, 50) p.Save(SpecialFolder.Desktop.Child("te""st.jpg"), picture.SaveAsJPEG)

I looked at http://documentation.xojo.com/api/graphics/picture.html#picture-save and there’s no mention of that Method raising an exception or what exceptions it could raise.

I then looked at http://documentation.xojo.com/api/files/folderitem.html and there’s one mention of an exception but its unrelated so again no mention of the exceptions that could be raised. Page Not Found — Xojo documentation nothing related to the issue.

So I guess my concern is, how are users meant to find out what exceptions can be raised by the code they are using without having to revert back to http://documentation.xojo.com/api/language/runtime.htmlException every time they write a line of code and checking it with a fine toothed comb or actively breaking their code to see what exceptions are raised?

Maybe we could have a nice prominent table somewhere on each page that raises an exception that lists the exceptions that can be raised so people know its even a thing that can happen?

Thoughts or have I missed something?

see <https://xojo.com/issue/49427>

I’m fairly sure there’s another FR to document what exceptions framework methods can raise

We will certainly need to go through the documentation and make sure that anything that can throw an exception, documents what exceptions it can throw and why.

Having said that, I think in the overwhelming majority of cases, users will catch RuntimeException and bail if that occurs. In most cases, whatever process is running usually can’t recover from an exception. For example, If the user clicks a button and that button saves a file to disk but something goes wrong that throws an exception, the app is likely to report that and ask the user to try again. This isn’t always true but I suspect it’s true more often than not.

Users will then default to RuntimeException and in cases where they discover that perhaps they can recover or can provide a more useful error message for tracking down the source of the problem (and potentially resolving it) they will use the more specific exceptions.

I also think that’s how most of us will use the “new” exceptions. I for sure, will check for cases/exception i can recover from and in all other cases rollback and inform the user/app to retry/abort.

Great news Geoff, thanks for the quick response. I see that Paul has already added some Exception tables, the format looks great, thanks Paul!

[quote=436532:@Geoff Perlman]
Having said that, I think in the overwhelming majority of cases, users will catch RuntimeException and bail if that occurs.[/quote]
I sure hope they don’t as this would be almost as bad as just never checking for error codes.

Java uses exceptions for a lot of error reporting and the WORST thing you can do is just catch everything unspecifically
See error # 2 here https://stackify.com/common-mistakes-handling-java-exception/

About the only difference for Xojo is that Xojo doesnt have a means to specify what exceptions a method might throw (like Java does)

I’m looking forward to API 2.0. And I guess we can take it as a fact that Exceptions and Exception Handling is going to be even more important when using API 2.0.

Having good documentation helps a lot.

That can be debated. Both are neither wrong nor the only good option. The fact remains: we will need to catch Exceptions - be it all or specific ones.

But… Exception Handling in Xojo is in a bad shape (one could even say: it’s broken)! With Exception Handling not working as expected, having API 2.0 and good Docs about Exceptions isn’t worth much… :frowning:

Don’t get me wrong - I’m looking forward to API 2.0. But first of all, we need a reliable Exception Handling in Xojo. Without it, we can’t even properly Beta test what’s going to come. Without it, our applications will behave weird and have unexpected issues.
Alright - for some simple “1 Document Window application | Example Project” it’s probably working. But any decent sized application using Modal Dialogs, Console Applications (Helpers apps) is currently not really reliable and stable when it comes to Exception Handling. And that’s for all BuildTargets (macOS, Windows - and I doubt that Linux is “stable”). For a start, have a look at this list.
So right now there is really no point in having API 2.0 and nice Exception Handling Docs. One could even say it’s safer to not use Exception Handling methods/API’s and go with the ErrorCode ones.

@Geoff Perlman : Do you agree that Exception Handling is important to build reliable applications and therefore kind of a requirement for API 2.0?

Having said this - it’s not a rant. Just some facts (of existing Feedback cases) and my personal opinion of what we need first - before API 2.0 and Docs. I look at this as a chance for the Xojo Framework - to finally have a reliable Exception Handling. It’s much needed and I consider this even required for the API 2.0 to come. So if you would ask me:

  1. Make Exception Handling rock solid (and since this could introduce new issues, first get out a 2019r2 with all other important Bugs and regressions fixed)
  2. Only once Exception Handling is working reliably (and proven to be working in a Release) get the API 2.0 in Beta
  3. And to be able to use it efficiently - thanks for good and improved Docs about Exceptions in API 2.0 (and existing API), as this will help developers both new to Xojo and those using Xojo for quite some time and transitioning to the newer API and using more-and-more Exception Handling in the time to come.

Another issue to consider is “upgradability” - I recently changed a class from being a subclass of HTTPSecureSocket to URLConnection. It was odd that some of the method names were close but different, e.g. URLConnection.ReceivingProgressed vs. HTTPSecureSocket.ReceiveProgress but the real problem was the error behavior: URLConnection throws errors, while HTTPSecureSocket triggers the error Event.

In this real-world example, my software was tested and worked fine, only to later crash the app with an unhandled exception - an edge case I hadn’t tested properly (Network offline completely).

I’m worried on three levels:

  • Why the subtle renaming of methods ReceiveProgress --> ReceivingProgressed ?
  • Why the (rather dramatic) change in behavior?
  • Why so little testing before it was released?

Additional issue (that may be the bigger one): Just what is the “exception throwing” behavior for an asynchronous, possibly threaded process going to look like? With a class that has an Error event, you know exactly where all errors are going to show up. With a class which raises exceptions…it’s unclear. Can an exception just pop up out of the blue? Are we guaranteed that all exceptions will be channeled through the URLConnection.Error event?

Short of making the compiler force you to write try catch around everything that can throw n exception its entirely possible that, like error codes, you just neglect to catch errors and end up with issues at runtime

I’m sure there are things that in theory could be done but then you’re likely going to have to change Xojo in significant ways
To the point that its no longer Xojo etc

Its a tricky problem either way