Julia: Undocumented exceptions

[mschauer]

Some days ago I generated a list of Exceptions without inline documentation. Here it is:

 Base.DNSError
 Base.Distributed.BatchProcessingError
 Base.LibGit2.Error.GitError
 Base.LinAlg.ARPACKException
 Base.LinAlg.LAPACKException
 Base.LinAlg.PosDefException
 Base.LinAlg.RankDeficientException
 Base.LinAlg.SingularException
 Base.Pkg.Entry.PkgTestError
 Base.Pkg.PkgError
 Base.Pkg.Resolve.MaxSum.UnsatError
 Base.PrecompilableError
 Base.SimdLoop.SimdError
 Base.SparseArrays.CHOLMOD.CHOLMODException
 Base.SparseArrays.UMFPACK.MatrixIllConditionedException
 Base.Test.FallbackTestSetException
 Base.UVError                                                          
 ~Base.WrappedException~   
 InvalidStateException
 SegmentationFault
 UnicodeError

Some of those are quite prominent, e.g. PosDefException.

[Vaibhavdixit02]

Hey I would like to work on it can someone help me out on how to move forward?

[mschauer]

Nice. Maybe we can collect some docstring proposals here. While we'll happily explain the howto, finding the right words for some of these exceptions needs some knowledge. For example, I myself also do not know what Base.WrappedException is for and could not write a docstring.

[Vaibhavdixit02]

Can you suggest how to move forward, I can't seem to understand that.

[mschauer]

Sure. Which Exception(s) would you be comfortable to start with? We'll go through the steps at https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#improving-documentation

[Vaibhavdixit02]

Base.LinAlg.LAPACKException
Base.LinAlg.SingularException

Are two of the errors that I am a little familiar with so I think it would be better to start with them.

[mschauer]

Do you want to prepare an initial pull request with reference to this issue so that we have something to base the discussion on?

[Vaibhavdixit02]

Yeah sure.

[mschauer]

A documented exception (example: DimensionMismatch) has

• a docstring explaining use and perhaps arguments to the constructor https://github.com/JuliaLang/julia/blob/b76c0fac09686f70317c450f7b536bb020b34381/base/array.jl#L5
• and an entry in https://github.com/JuliaLang/julia/blob/19b3ca7be9f47099dcf192b57e3b044c571ed155/doc/src/stdlib/base.md#L284
• Exceptions can provide a showerror method to show a descriptive representation of an exception object (for example useful for exceptions with field info with magic numbers inherited from LAPACK, https://github.com/JuliaLang/julia/blob/5fa91e296c1ef6a340163df81067d6ee314f03b2/base/linalg/exceptions.jl)

[Bubblemelon]

Hi, is anyone working on the other exceptions?

[samoconnor]

7841

[mschauer]

Update (using (subtypes(Exception)[map(x-> nothing != findfirst("No documentation found.", string(Base.Docs.doc(x))), subtypes(Exception))])

Base.CodePointError
Base.IOError
Base.InvalidCharError
Base.PrecompilableError
Base.SimdLoop.SimdError
CapturedException
Core.Compiler.DimensionMismatch
Core.Compiler.InvalidCodeError
Core.Compiler.KeyError
Distributed.BatchProcessingError
InvalidStateException
LibGit2.Error.GitError
LinearAlgebra.ARPACKException
LinearAlgebra.LAPACKException
LinearAlgebra.PosDefException
LinearAlgebra.RankDeficientException
LinearAlgebra.SingularException
Pkg.Resolve.MaxSum.UnsatError
Pkg.Types.PkgError
Pkg.Types.ResolverError
SegmentationFault
Sockets.DNSError
SuiteSparse.CHOLMOD.CHOLMODException
SuiteSparse.UMFPACK.MatrixIllConditionedException
Test.FallbackTestSetException

[Jutho]

Not sure why LinearAlgebra.ARPACKException is even still defined? This could probably be removed?

[mschauer]

Good find. I opened a corresponding issue at JuliaLinearAlgebra/Arpack.jl/issues/64, which still uses this

[AtsushiSakai]

I added docstring for Sockets.DNSError in #34189