Document the remaining Exception types

[jonathanstowe]

Rather than having a bunch of whackamole issues for each un-documented X:: class this is a placeholder for the documentation of the remaining undocumented exception sub-classes.

The exceptions should all be documented so that they can be linked from the documentation for the places that they might be thrown, as well as searchable for people who find they have an exception that they don't quite know where it comes from.

It is possible that some boilerplate for this could be generated automatically.

There are however a lot of exceptions so I have made #516 to discuss a better way of managing them so they don't swamp the rest of the type documentation.

[AlexDaniel]

Is there a list of all exception types?

[jonathanstowe]

No but for the most part they are defined in the https://github.com/rakudo/rakudo/blob/nom/src/core/Exception.pm so it would be fairly easy for someone who is so motivated to make one :)

[zoffixznet]

cd $(mktemp -d); git checkout https://github.com/rakudo/rakudo/ .; grep -R 'X::' | perl -nE 'my ($e) = /X::[^\s,;()'\''."\]`|]+/g; $e =~ s/:$//; say $e' | sort | uniq

?

I got these with the above:

X::a
X::AdHoc
X::Adverb
X::Anon::Augment
X::Anon::Multi
X::Assignment::ArrayShapeMismatch
X::Assignment::RO
X::Assignment::RO::Comp
X::Assignment::ToShaped
X::Attribute::NoPackage
X::Attribute::Package
X::Attribute::Regex
X::Attribute::Required
X::Attribute::Scope::Package
X::Attribute::Undeclared
X::Augment::NoSuchType
X::Backslash::NonVariableDollar
X::Backslash::UnrecognizedSequence
X::Base
X::Bind
X::Bind::NativeType
X::Bind::Slice
X::Bind::ZenSlice
X::Buf::AsStr
X::Buf::Pack
X::Buf::Pack::NonASCII
X::Caller::NotDynamic
X::Cannot::Empty
X::Cannot::Lazy
X::Cannot::New
X::Channel::ReceiveOnClosed
X::Channel::SendOnClosed
X::Comp
X::Comp::AdHoc
X::Comp::BeginTime
X::Comp::FailGoal
X::Comp::Group
X::Comp::NYI
X::Composition::NotComposable
X::Comp::Trait::NotOnNative
X::Comp::Trait::Scope
X::Comp::Trait::Unknown
X::CompUnit::AmbiguousDependencySpecification
X::CompUnit::UnsatisfiedDependency
X::Constructor::Positional
X::Control
X::ControlFlow
X::ControlFlow::Return
X::DateTime::InvalidDeltaUnit
X::DateTime::TimezoneClash
X::Declaration::OurScopeInRole
X::Declaration::Scope
X::Declaration::Scope::Multi
X::Does::TypeObject
X::Dynamic::NotFound
X::Dynamic::Package
X::Dynamic::Postdeclaration
X::Eval::NoSuchLang
X::Experimental
X::EXPORTHOW::Conflict
X::EXPORTHOW::InvalidDirective
X::EXPORTHOW::NothingToSupersede
X::Export::NameClash
X::Hash::Store::OddNumber
X::HTTP
X::HyperOp::Infinite
X::HyperOp::NonDWIM
X::HyperWhatever::Multiple
X::IllegalDimensionInShape
X::IllegalOnFixedDimensionArray
X::Immutable
X::Import::MissingSymbols
X::Import::NoSuchTag
X::Import::OnlystarProto
X::Import::Positional
X::Import::Redeclaration
X::Inheritance::NotComposed
X::Inheritance::SelfInherit
X::Inheritance::UnknownParent
X::Inheritance::Unsupported
X::InvalidType
X::InvalidTypeSmiley
X::Invalid::Value
X::IO
X::IO::Chdir
X::IO::Chmod
X::IO::Copy
X::IO::Cwd
X::IO::Dir
X::IO::Directory
X::IO::DoesNotExist
X::IO::Link
X::IO::Mkdir
X::IO::Move
X::IO::NotAFile
X::IO::Rename
X::IO::Rmdir
X::IO::Symlink
X::IO::Unknown
X::IO::Unlink
X::Item
X::KeyReducer::ResultObtained
X::Language::Unsupported
X::Last
X::LibNone
X::Localizer::NoContainer
X::Lock::ConditionVariable::New
X::Match::Bool
X::Method::InvalidQualifier
X::Method::NotFound
X::Method::Private::Permission
X::Method::Private::Unqualified
X::Mixin::NotComposable
X::MOP
X::Multi::Ambiguous
X::Multi::NoMatch
X::MustBeParametric
X::Next
X::NoDispatcher
X::NoSuchSymbol
X::NotEnoughDimensions
X::NotParametric
X::NQP::NotFound
X::Numeric::Confused
X::Numeric::DivideByZero
X::Numeric::DivisionByZero
X::Numeric::Overflow
X::Numeric::Real
X::Numeric::Underflow
X::NYI
X::NYI::Available
X::NYI::BigInt
X::Obsolete
X::OS
X::OutOfRange
X::Package::Stubbed
X::Package::UseLib
X::Pairup::OddNumber
X::Parameter::AfterDefault
X::Parameter::BadType
X::Parameter::Default
X::Parameter::Default::TypeCheck
X::Parameter::InvalidType
X::Parameter::MultipleTypeConstraints
X::Parameter::Placeholder
X::Parameter::RW
X::Parameter::Twigil
X::Parameter::TypedSlurpy
X::Parameter::WrongOrder
X::PhaserExceptions
X::PhaserExceptions:D
X::Phaser::Multiple
X::Phaser::PrePost
X::Placeholder::Attribute
X::Placeholder::Block
X::Placeholder::Mainline
X::Placeholder::NonPlaceholder
X::Pod
X::PoisonedAlias
X::Pragma::CannotPrecomp
X::Pragma::CannotWhat
X::Pragma::MustOneOf
X::Pragma::NoArgs
X::Pragma::OnlyOne
X::Pragma::UnknownArg
X::Proc::Async
X::Proc::Async::AlreadyStarted
X::Proc::Async::CharsOrBytes
X::Proc::Async::MustBeStarted
X::Proc::Async::OpenForWriting
X::Proc::Async::TapBeforeSpawn
X::Proceed
X::Proc::Unsuccessful
X::Promise::CauseOnlyValidOnBroken
X::Promise::Combinator
X::Promise::Vowed
X::PseudoPackage::InDeclaration
X::Range::InvalidArg
X::Redeclaration
X::Redeclaration::Outer
X::Redo
X::Roast::Channel
X::Role::Initialization
X::Role::Parametric::NoSuchCandidate
X::Routine::Unwrap
X::SecurityPolicy
X::SecurityPolicy::Eval
X::Seq::Consumed
X::Seq::NotIndexable
X::Sequence::Deduction
X::Set::Coerce
X::Signature::NameClash
X::Signature::Placeholder
X::Str::Match::x
X::Str::Numeric
X::Str::Sprintf::Directives::BadType
X::Str::Sprintf::Directives::Count
X::Str::Sprintf::Directives::Unsupported
X::Str::Trans::IllegalKey
X::Str::Trans::InvalidArg
X::StubCode
X::Subscript::FromEnd
X::Subscript::Negative
X::Succeed
X::Supply::Combinator
X::Supply::Migrate::Needs
X::Supply::New
X::Syntax
X::Syntax::AddCategorical::TooFewParts
X::Syntax::AddCategorical::TooManyParts
X::Syntax::Adverb
X::Syntax::Argument::MOPMacro
X::Syntax::Augment::Adverb
X::Syntax::Augment::Illegal
X::Syntax::Augment::WithoutMonkeyTyping
X::Syntax::BlockGobbled
X::Syntax::CannotMeta
X::Syntax::Comment::Embedded
X::Syntax::ConditionalOperator::PrecedenceTooLoose
X::Syntax::ConditionalOperator::SecondPartGobbled
X::Syntax::ConditionalOperator::SecondPartInvalid
X::Syntax::Confused
X::Syntax::DuplicatedPrefix
X::Syntax::Extension::Category
X::Syntax::Extension::Null
X::Syntax::Extension::SpecialForm
X::Syntax::Extension::TooComplex
X::Syntax::InfixInTermPosition
X::Syntax::KeywordAsFunction
X::Syntax::Malformed
X::Syntax::Malformed::Elsif
X::Syntax::Missing
X::Syntax::Name::Null
X::Syntax::NegatedPair
X::Syntax::NonAssociative
X::Syntax::NoSelf
X::Syntax::Number::IllegalDecimal
X::Syntax::Number::LiteralType
X::Syntax::Number::RadixOutOfRange
X::Syntax::P5
X::Syntax::Perl5Var
X::Syntax::Pod::BeginWithoutEnd
X::Syntax::Pod::BeginWithoutIdentifier
X::Syntax::Regex::Adverb
X::Syntax::Regex::MalformedRange
X::Syntax::Regex::NonQuantifiable
X::Syntax::Regex::NullRegex
X::Syntax::Regex::SolitaryBacktrackControl
X::Syntax::Regex::SolitaryQuantifier
X::Syntax::Regex::SpacesInBareRange
X::Syntax::Regex::UnrecognizedMetachar
X::Syntax::Regex::UnrecognizedModifier
X::Syntax::Regex::Unspace
X::Syntax::Regex::Unterminated
X::Syntax::Reserved
X::Syntax::Self::WithoutObject
X::Syntax::Signature::InvocantMarker
X::Syntax::Signature::InvocantNotAllowed
X::Syntax::Term::MissingInitializer
X::Syntax::Type::Adverb
X::Syntax::UnlessElse
X::Syntax::Variable::BadType
X::Syntax::Variable::ConflictingTypes
X::Syntax::Variable::IndirectDeclaration
X::Syntax::Variable::Initializer
X::Syntax::Variable::Match
X::Syntax::Variable::MissingInitializer
X::Syntax::Variable::Numeric
X::Syntax::Variable::Twigil
X::Syntax::VirtualCall
X::Take
X::Temporal
X::Temporal::InvalidFormat
X::TooLateForREPR
X::TooManyDimensions
X::Trait::NotOnNative
X::Trait::Scope
X::Trait::Unknown
X::TypeCheck
X::TypeCheck::Argument
X::TypeCheck::Assignment
X::TypeCheck::Binding
X::TypeCheck::Return
X::TypeCheck::Splice
X::Undeclared
X::Undeclared::Symbols
X::Undeclared::Symbols:D
X::UnitScope::Invalid
X::UnitScope::TooLate
X::Value::Dynamic
X::Warn
X::WheneverOutOfScope
X::Worry
X::Worry::P5
X::Worry::P5::BackReference
X::Worry::P5::LeadingZero
X::Worry::P5::Reference
X::Y

[awwaiid]

I ran that in roast/ instead of rakudo and got a smaller and somewhat different list. These are mentioned in Rakudo but not Roast. Some of them look like they are the role for a common exception.

X::Attribute::Scope::Package
X::Base
X::Comp::FailGoal
X::CompUnit::AmbiguousDependencySpecification
X::Control
X::Experimental
X::IllegalDimensionInShape
X::IO
X::IO::Unknown
X::KeyReducer::ResultObtained
X::Language::Unsupported
X::LibNone
X::MOP
X::MustBeParametric
X::Numeric::DivisionByZero
X::Numeric::Underflow
X::OS
X::PhaserExceptions:D
X::Pod
X::Proc::Async
X::SecurityPolicy::Eval
X::Str::Sprintf::Directives::BadType
X::Str::Sprintf::Directives::Count
X::Str::Sprintf::Directives::Unsupported
X::Subscript::FromEnd
X::Supply::New
X::Syntax
X::Temporal
X::TooManyDimensions
X::Undeclared::Symbols:D
X::WheneverOutOfScope

I didn't find any that are mentioned in Roast but not Rakudo :)

[JJ]

Would it be possible to create some kind of documentation directly from their PODs?

[JJ]

I think that this issue has not received the attention it deserves. We have a whole bunch of X:::: classes documented, sometimes with a single method, but a tail of stuff going all the way back to Mu. Check out X::IO::Chdir, for instance.
I don't see an easy way of changing the tooling (nothing is easy with htmlify.p6) to change that, but we could have a few /language/ pages describing exceptions at the second level (X::IO; for instance).

[coke]

We'd still have to generate each individual page, so I'm not sure what part here would be automated.

FYI: You can get a shell of the doc page for a type using util/new-type.p6

You can get a list of the missing types with util/missing-types.p6