Document how unexpected errors are generated

[tarikeshaq]

uniffi generates scaffolding code that catches panics, and it converts those panics into errors in the consuming language.

In Kotlin, that error is an exception called InternalException. We don't document that anywhere, so consumers have no way of knowing that. Those errors are not meant to be caught, but if a consumer still decides to catch them, they should know what type of error they're catching without having to look at the bindings.

┆Issue is synchronized with this Jira Task ┆Issue Number: UNIFFI-71

[tarikeshaq]

As a part of this, it could be useful to rename the InternalException to a PanicException as was discussed in https://github.com/mozilla/uniffi-rs/pull/486#discussion_r653097740

Of course, this would be a breaking change though.

[bendk]

I like this direction. Couple thoughts:

• Maybe it should even be InternalError or PanicError, since you can't recover from them in general.
• I think there are a couple other ways to raise an InternalException. I was just working on swift, which has a whole enum of them. Maybe this could be combined with #978, and we could have a base InternalError and PanicError could be one of it's subclasses
• I just remembered that InternalError is also a java error, so maybe UniffiError would be a better name.

[rfk]

it could be useful to rename the InternalException to a PanicException

FWIW, I'm lightly against exposing Rust-specific terminology in the public API of the generated components - I like to think that consumers shouldn't need to know or care about Rust as it's just an implementation detail of a nice Kotlin/Swift/Whatever component that they're using, so they shouldn't be expected to know what a "panic" is in any detail.

(I would put exactly zero effort into stopping you from making this change if you feel strongly about it, just wanted to share my perspective 😁).