clean up and finish logging docs

Author: lkdvos

docs/make.jl

@@ -52,8 +52,6 @@ makedocs(;
     ],
     expandfirst = ["interface.md", "stopping_criterion.md"],
     plugins = [bib, links],
-    warnonly = true
-
 )
 deploydocs(; repo = "github.com/JuliaManifolds/AlgorithmsInterface.jl", push_preview = true)
 #back to main env

docs/src/interface.md

@@ -107,7 +107,7 @@ end
 ```
 
 Note that we are only focussing on the actual algorithm, and *not* incrementing the iteration counter.
-These kinds of bookkeeping should be handled by the [`increment!(state)`](@ref) function, which will by default already increment the iteration counter.
+These kinds of bookkeeping should be handled by the [`AlgorithmsInterface.increment!`](@ref) function, which will by default already increment the iteration counter.
 The following generic functionality is therefore enough for our purposes, and does *not* need to be defined.
 Nevertheless, if additional bookkeeping would be desired, this can be achieved by overloading that function:
 

docs/src/logging.md

@@ -24,14 +24,14 @@ The logging system aims to achieve these goals by separating the logging logic i
 These parts can be roughly described as *events* and *actions*, where the logging system is responsible for mapping between them.
 Concretely, we have:
 
-* **When do we log?** → an [`AlgorithmLogger`](@ref) mapping events to actions.
-* **What happens when we log?** → a [`LoggingAction`](@ref).
+* **When do we log?** → an [`with_algorithmlogger`](@ref) to control how to map events to actions.
+* **What happens when we log?** → a [`LoggingAction`](@ref) to determine what to do when an event happens.
 
 This separation allows users to compose rich behaviors (printing, collecting statistics, plotting) without modifying algorithm code, and lets algorithm authors emit domain‑specific events.
 
 ## Using the default logging actions
 
-Continuing from the [Stopping Criteria](@ref) page, we have our Heron's method implementation ready:
+Continuing from the [Stopping Criteria](@ref sec_stopping) page, we have our Heron's method implementation ready:
 
 ```@example Heron
 using AlgorithmsInterface
@@ -97,7 +97,7 @@ nothing # hide
 ```
 
 To activate this logger, we wrap the section of code that we want to enable logging for, and map the `:PostStep` context to our action.
-This is achieved through the [`with_algorithmlogger`](@ref) function, and uses Julia's `with` function to set the [`ALGORITHM_LOGGER`](@ref) scoped value:
+This is achieved through the [`with_algorithmlogger`](@ref) function, which under the hood uses Julia's `with` function to manipulate a scoped value.
 
 ```@example Heron
 with_algorithmlogger(:PostStep => iter_printer) do
@@ -246,7 +246,7 @@ Let's implement a more sophisticated example: tracking iteration statistics.
 To implement a custom [`LoggingAction`](@ref), you need:
 
 1. A concrete subtype of `LoggingAction`.
-2. An implementation of [`handle_message!`](@ref) that defines the behavior.
+2. An implementation of [`AlgorithmsInterface.handle_message!`](@ref) that defines the behavior.
 
 The signature of `handle_message!` is:
 
@@ -306,7 +306,7 @@ This pattern of collecting data during iteration and post-processing afterward i
 
 ## [The AlgorithmLogger](@id sec_algorithmlogger)
 
-The [`AlgorithmLogger`](@ref) is the dispatcher that routes logging events to actions.
+The [`AlgorithmsInterface.AlgorithmLogger`](@ref) is the dispatcher that routes logging events to actions.
 Understanding its design helps when adding custom logging contexts.
 
 ### How logging events are emitted
@@ -315,21 +315,19 @@ Inside the `solve!` function, logging events are emitted at key points:
 
 ```julia
 function solve!(problem::Problem, algorithm::Algorithm, state::State; kwargs...)
-    logger = algorithm_logger()
-    
     initialize_state!(problem, algorithm, state; kwargs...)
-    emit_message(logger, problem, algorithm, state, :Start)
+    emit_message(problem, algorithm, state, :Start)
 
     while !is_finished!(problem, algorithm, state)
-        emit_message(logger, problem, algorithm, state, :PreStep)
+        emit_message(problem, algorithm, state, :PreStep)
 
         increment!(state)
         step!(problem, algorithm, state)
 
-        emit_message(logger, problem, algorithm, state, :PostStep)
+        emit_message(problem, algorithm, state, :PostStep)
     end
 
-    emit_message(logger, problem, algorithm, state, :Stop)
+    emit_message(problem, algorithm, state, :Stop)
 
     return state
 end
@@ -364,7 +362,14 @@ AlgorithmsInterface.set_global_logging_state!(previous_state)
 nothing # hide
 ```
 
-When logging is disabled globally, [`algorithm_logger`](@ref) returns `nothing`, and `emit_message` becomes a no-op with minimal overhead.
+This works since the default implementation of [`emit_message`](@ref) first retrieves the current logger through [`AlgorithmsInterface.algorithm_logger`](@ref):
+
+```julia
+emit_message(problem, algorithm, state, context; kwargs...) =
+    emit_message(algorithm_logger(), problem, algorithm, state, context; kwargs...)
+```
+
+When logging is disabled globally, [`algorithm_logger`](@ref AlgorithmsInterface.algorithm_logger) returns `nothing`, and `emit_message` becomes a no-op with minimal overhead.
 
 ### Error isolation
 
@@ -493,7 +498,7 @@ Private = true
 You have now seen the three pillars of the AlgorithmsInterface:
 
 * [**Interface**](@ref sec_interface): Defining algorithms with `Problem`, `Algorithm`, and `State`.
-* [**Stopping criteria**](@ref): Controlling when iteration halts with composable conditions.
+* [**Stopping criteria**](@ref sec_stopping): Controlling when iteration halts with composable conditions.
 * [**Logging**](@ref sec_logging): Instrumenting execution with flexible, composable actions.
 
 Together, these patterns encourage modular, testable, and maintainable iterative algorithm design.

docs/src/stopping_criterion.md

@@ -2,7 +2,7 @@
 CollapsedDocStrings = true
 ```
 
-# Stopping criteria
+# [Stopping criteria](@id sec_stopping)
 
 Continuing the square‑root story from the [Interface](@ref sec_interface) page, we now decide **when** the iteration should halt.
 A stopping criterion encapsulates halting logic separately from the algorithm update rule.

src/AlgorithmsInterface.jl

@@ -20,13 +20,20 @@ include("interface/interface.jl")
 include("stopping_criterion.jl")
 include("logging.jl")
 
+# general interface
 export Algorithm, Problem, State
+export initialize_state, initialize_state!
+
+export step!, solve, solve!
+
+# stopping criteria
 export StoppingCriterion, StoppingCriterionState
 export StopAfter, StopAfterIteration, StopWhenAll, StopWhenAny
-export AlgorithmLogger, with_algorithmlogger, emit_message
+
+export is_finished, is_finished!, get_reason, indicates_convergence
+
+# Logging interface
 export LoggingAction, CallbackAction, IfAction, GroupAction
-export is_finished, is_finished!
-export initialize_state, initialize_state!
-export step!, solve, solve!
+export with_algorithmlogger, emit_message
 
 end # module AlgorithmsInterface

src/logging.jl

@@ -87,9 +87,27 @@ end
 # Algorithm Logger
 # ----------------
 """
-    AlgorithmLogger(context => action, ...)
+    AlgorithmLogger(context => action, ...) -> logger
 
 Logging transformer that handles the logic of dispatching logging events to logging actions.
+This is implemented through `logger[context]`.
+
+See also the scoped value [`AlgorithmsInterface.algorithm_logger`](@ref).
+"""
+struct AlgorithmLogger
+    actions::Dict{Symbol, LoggingAction}
+end
+AlgorithmLogger(args::Pair...) = AlgorithmLogger(Dict{Symbol, LoggingAction}(args...))
+
+Base.getindex(logger::AlgorithmLogger, context::Symbol) = get(logger.actions, context, nothing)
+
+"""
+    with_algorithmlogger(f, (context => action)::Pair{Symbol, LoggingAction}...)
+    with_algorithmlogger((context => action)::Pair{Symbol, LoggingAction}...) do
+        # insert arbitrary code here
+    end
+
+Run the given zero-argument function `f()` while mapping events of given `context`s to their respective `action`s.
 By default, the following events trigger a logging action with the given `context`:
 
 |  context  |              event                  |
@@ -99,16 +117,11 @@ By default, the following events trigger a logging action with the given `contex
 | :PostStep | The solver has taken a step.        |
 | :Stop     | The solver has finished.            |
 
-Specific algorithms can associate other events with other contexts.
+However, further events and actions can be emitted through the [`emit_message`](@ref) interface.
 
 See also the scoped value [`AlgorithmsInterface.algorithm_logger`](@ref).
 """
-struct AlgorithmLogger
-    actions::Dict{Symbol, LoggingAction}
-end
-AlgorithmLogger(args::Pair...) = AlgorithmLogger(Dict{Symbol, LoggingAction}(args...))
-
-function with_algorithmlogger(f, args...)
+@inline function with_algorithmlogger(f, args...)
     logger = AlgorithmLogger(args...)
     return with(f, ALGORITHM_LOGGER => logger)
 end
@@ -153,18 +166,21 @@ end
     emit_message(algorithm_logger, problem::Problem, algorithm::Algorithm, state::State, context::Symbol; kwargs...) -> nothing
 
 Use the current or the provided algorithm logger to handle the logging event of the given `context`.
-The [`AlgorithmLogger`](@ref) is responsible for dispatching the correct events to the correct [`LoggingAction`](@ref)s.
+The first signature should be favored as it correctly handles accessing the `logger` and respecting global toggles for enabling and disabling the logging system.
+
+The second signature should be used exclusively in (very) hot loops, where the overhead of [`AlgorithmsInterface.algorithm_logger()`](@ref) is too large.
+In this case, you can manually extract the `algorithm_logger()` once outside of the hot loop.
 """
 emit_message(problem::Problem, algorithm::Algorithm, state::State, context::Symbol; kwargs...) =
     emit_message(algorithm_logger(), problem, algorithm, state, context; kwargs...)
 emit_message(::Nothing, problem::Problem, algorithm::Algorithm, state::State, context::Symbol; kwargs...) =
     nothing
 function emit_message(
-        alglogger::AlgorithmLogger, problem::Problem, algorithm::Algorithm, state::State, context::Symbol;
+        logger::AlgorithmLogger, problem::Problem, algorithm::Algorithm, state::State, context::Symbol;
         kwargs...
     )
     @noinline; @nospecialize
-    action::LoggingAction = @something(get(alglogger.actions, context, nothing), return nothing)
+    action::LoggingAction = @something(logger[context], return nothing)
 
     # Try-catch around logging to avoid stopping the algorithm when a logging action fails
     # but still emit an error message