add docstring for LinearVerbosity, spruce up docs page

Author: jClugstor

docs/src/basics/common_solver_opts.md

@@ -29,50 +29,38 @@ solve completely. Error controls only apply to iterative solvers.
 
 ## Verbosity Controls
 
-The verbosity system in LinearSolve.jl provides fine-grained control over the diagnostic messages, warnings, and errors that are displayed during the solution of linear systems.
+The verbosity system in LinearSolve.jl provides fine-grained control over the diagnostic messages, warnings, and errors that are displayed during the solution of linear systems. To use this system, a keyword argument `verbose` is provided to `solve`. 
 
-The verbosity system is organized hierarchically into three main categories:
-
-1. Error Control - Messages related to fallbacks and error handling
-2. Performance - Messages related to performance considerations
-3. Numerical - Messages related to numerical solvers and iterations
-
-Each category can be configured independently, and individual settings can be adjusted to suit your needs.
-
-### Verbosity Levels
-The following verbosity levels are available:
-
-#### Individual Settings
-These settings are meant for individual settings within a category. These can also be used to set all of the individual settings in a group to the same value.
-- SciMLLogging.None() - Suppress all messages
-- SciMLLogging.Info() - Show message as log message at info level
-- SciMLLogging.Warn() - Show warnings (default for most settings)
-- SciMLLogging.Error() - Throw errors instead of warnings
-- SciMLLogging.Level(n) - Show messages with a log level setting of n
-
-#### Group Settings
-These settings are meant for controlling a group of settings. 
-- SciMLLogging.Default() - Use the default settings
-- SciMLLogging.All() - Show all possible messages
+```@docs
+LinearVerbosity
+```
 
 ### Basic Usage 
 
 #### Global Verbosity Control
 
-```julia 
+```julia
 using LinearSolve
 
 # Suppress all messages
 verbose = LinearVerbosity(SciMLLogging.None())
 prob = LinearProblem(A, b)
 sol = solve(prob; verbose=verbose)
 
-# Show all messages
-verbose = LinearVerbosity(SciMLLogging.All())
+# Show only essential messages (critical errors and fatal issues)
+verbose = LinearVerbosity(SciMLLogging.Minimal())
+sol = solve(prob; verbose=verbose)
+
+# Use default settings (balanced verbosity for typical usage)
+verbose = LinearVerbosity(SciMLLogging.Standard())
+sol = solve(prob; verbose=verbose)
+
+# Show comprehensive debugging information
+verbose = LinearVerbosity(SciMLLogging.Detailed())
 sol = solve(prob; verbose=verbose)
 
-# Use default settings
-verbose = LinearVerbosity(SciMLLogging.Default())
+# Show all messages (maximum verbosity)
+verbose = LinearVerbosity(SciMLLogging.All())
 sol = solve(prob; verbose=verbose)
 ```
 
@@ -82,7 +70,7 @@ sol = solve(prob; verbose=verbose)
 # Customize by category
 verbose = LinearVerbosity(
     error_control = SciMLLogging.Warn(),   # Show warnings for error control related issues
-    performance = SciMLLogging.None(),     # Suppress performance messages
+    performance = SciMLLogging.Silent(),     # Suppress performance messages
     numerical = SciMLLogging.Info()        # Show all numerical related log messages at info level
 )
 
@@ -95,23 +83,12 @@ The verbosity settings for the toggles are automatically passed to the group obj
 ```julia
 # Set specific message types
 verbose = LinearVerbosity(
-    default_lu_fallback = SciMLLogging.Info(),                     # Show info when LU fallback is used
-    KrylovJL_verbosity = SciMLLogging.Warn(),                      # Show warnings from KrylovJL
-    no_right_preconditioning = SciMLLogging.None(),                # Suppress right preconditioning messages
+    default_lu_fallback = SciMLLogging.InfoLevel(),                     # Show info when LU fallback is used
+    KrylovJL_verbosity = SciMLLogging.WarnLevel(),                      # Show warnings from KrylovJL
+    no_right_preconditioning = SciMLLogging.Silent(),                # Suppress right preconditioning messages
     KrylovKit_verbosity = SciMLLogging.Level(KrylovKit.WARN_LEVEL) # Set KrylovKit verbosity level using KrylovKit's own verbosity levels
 )
 
 sol = solve(prob; verbose=verbose)
 
-```
-
-#### Verbosity Levels
-##### Error Control Settings
-- default_lu_fallback: Controls messages when falling back to LU factorization (default: Warn)
-##### Performance Settings
-- no_right_preconditioning: Controls messages when right preconditioning is not used (default: Warn)
-##### Numerical Settings
-- using_IterativeSolvers: Controls messages when using the IterativeSolvers.jl package (default: Warn)
-- IterativeSolvers_iterations: Controls messages about iteration counts from IterativeSolvers.jl (default: Warn)
-- KrylovKit_verbosity: Controls messages from the KrylovKit.jl package (default: Warn)
-- KrylovJL_verbosity: Controls verbosity of the KrylovJL.jl package (default: None)
+```

src/verbosity.jl

@@ -1,3 +1,72 @@
+"""
+    LinearVerbosity <: AbstractVerbositySpecifier
+
+Verbosity configuration for LinearSolve.jl solvers, providing fine-grained control over
+diagnostic messages, warnings, and errors during linear system solution.
+
+# Fields
+
+## Error Control Group
+- `default_lu_fallback`: Messages when falling back to LU factorization from other methods
+- `blas_errors`: Critical BLAS errors that stop computation
+- `blas_invalid_args`: BLAS errors due to invalid arguments
+
+## Performance Group
+- `no_right_preconditioning`: Messages when right preconditioning is not used
+
+## Numerical Group
+- `using_IterativeSolvers`: Messages when using the IterativeSolvers.jl package
+- `IterativeSolvers_iterations`: Iteration count messages from IterativeSolvers.jl
+- `KrylovKit_verbosity`: Verbosity level passed to KrylovKit.jl solvers
+- `KrylovJL_verbosity`: Verbosity level passed to Krylov.jl solvers
+- `HYPRE_verbosity`: Verbosity level passed to HYPRE solvers
+- `pardiso_verbosity`: Verbosity level passed to Pardiso solvers
+- `blas_info`: Informational messages from BLAS operations
+- `blas_success`: Success messages from BLAS operations
+- `condition_number`: Messages related to condition number calculations
+- `convergence_failure`: Messages when iterative solvers fail to converge
+
+# Constructors
+
+    LinearVerbosity(preset::AbstractVerbosityPreset)
+
+Create a `LinearVerbosity` using a preset configuration:
+- `SciMLLogging.None()`: All messages disabled
+- `SciMLLogging.Minimal()`: Only critical errors and fatal issues
+- `SciMLLogging.Standard()`: Balanced verbosity (default)
+- `SciMLLogging.Detailed()`: Comprehensive debugging information
+- `SciMLLogging.All()`: Maximum verbosity
+
+    LinearVerbosity(; error_control=nothing, performance=nothing, numerical=nothing, kwargs...)
+
+Create a `LinearVerbosity` with group-level or individual field control.
+
+# Examples
+
+```julia
+# Use a preset
+verbose = LinearVerbosity(SciMLLogging.Standard())
+
+# Set entire groups
+verbose = LinearVerbosity(
+    error_control = SciMLLogging.WarnLevel(),
+    numerical = SciMLLogging.InfoLevel()
+)
+
+# Set individual fields
+verbose = LinearVerbosity(
+    default_lu_fallback = SciMLLogging.InfoLevel(),
+    KrylovJL_verbosity = SciMLLogging.CustomLevel(1),
+    blas_errors = SciMLLogging.ErrorLevel()
+)
+
+# Mix group and individual settings
+verbose = LinearVerbosity(
+    numerical = SciMLLogging.InfoLevel(),  # Set all numerical to InfoLevel
+    blas_errors = SciMLLogging.ErrorLevel()  # Override specific field
+)
+```
+"""
 LinearSolve.@concrete struct LinearVerbosity <:
                                       AbstractVerbositySpecifier
     # Error control