Ad hoc exceptions are not documented well enough.

[van-de-bugger]

Problem or new feature

Look at Ad hock exceptions, and the next section, Typed exceptions: Ad hock exceptions are contrasted to Typed exceptions. A novice reader might get the impression that these are two different kinds of exceptions.

Suggestions

It would be nice to say that die "message" is actually throws a typed exception of X::AdHock type.

[arkiuat]

https://irclogs.raku.org/raku-beginner/2025-11-24.html is probably relevant

[coke]

To clarify after reading that irc log: X::AdHoc isa Exception.

[coke]

While adhoc is a type of exception like any other, the intent is that it is kind of default type - other (also typed) exceptions will be used in cases where a specific condition is being alerted on.

It is also possible that future versions of the language will convert more AdHoc exceptions to other (more specific) exceptions. When catching exceptions, it’s probably not helpful to have a specific catch handler for the type of AdHoc.

[arkiuat]

@coke, thanks, that's helpful. After reviewing all the evidence that people are having trouble clearly understanding this as currently presented, I'm thinking that (in addition to clarifying the text a bit) I should move the section "Ad hoc exceptions" to immediately follow the section on "Typed exceptions", right before the section "Catching exceptions".

Then the explanation of Ad hoc exceptions could be made in terms of what has already been explained about typed exceptions, incorporating what you've explained above about the intended use. That should be a lot clearer for most folks.

[arkiuat]

Just thinking out loud here:

The original issue wants us to say that die "message" actually throws a typed exception of X::AdHoc type, but it already says "Ad hoc exceptions can be used by calling die with a description of the error" which doesn't make this clear enough (in part because there's not enough context yet).

Adding a link to X::AdHoc would probably help, but about that page @lucs says (in the linked IRC excerpt) that when that document states "X::AdHoc is the type into which objects are wrapped if they are thrown as exceptions, but don't inherit from Exception." he's not sure what that means.

So clarifying and providing a little more context for that statement both here in https://docs.raku.org/language/exceptions#Ad_hoc_exceptions and also on the type document itself would help.

P. S. I just discovered https://github.com/Raku/doc/issues/3978 "Docs on exceptions do not mention failures at all" and I think maybe these two docs issues should be worked on in tandem.