From c2873d961c4d322acb9ba85efdf4f4d68739cc2e Mon Sep 17 00:00:00 2001 From: Olivier Cots Date: Sun, 30 Aug 2026 18:52:32 +0200 Subject: [PATCH] Fix parameter documentation anchors. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- BREAKING.md | 8 ++ CHANGELOG.md | 13 +++ Project.toml | 2 +- src/Strategies/contract/abstract_strategy.jl | 83 +++++++++----------- 4 files changed, 58 insertions(+), 48 deletions(-) diff --git a/BREAKING.md b/BREAKING.md index cc4851e0..855cde76 100644 --- a/BREAKING.md +++ b/BREAKING.md @@ -3,6 +3,14 @@ This document outlines all breaking changes introduced in CTBase v0.18.0-beta compared to v0.17.4. Use this guide to migrate your code and understand the impact of these changes. +## Non-breaking note (0.30.2-beta) + +- **Strategies — `parameter` documentation anchors**: split the docstrings for + the one-argument and two-argument `Strategies.parameter` methods so their API + anchors can be resolved independently by downstream documentation. **No + breaking change**: runtime behavior, public signatures, types, and names are + unchanged. No migration required. + ## Non-breaking note (0.30.1-beta) - **Plotting — Makie backend parity**: `CTBase.Plotting.MakieBackend` reached diff --git a/CHANGELOG.md b/CHANGELOG.md index ed2ea6ad..cb75f7bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,19 @@ All notable changes to CTBase will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.30.2-beta] - unreleased + +### 📚 Documentation + +- **`Strategies.parameter` cross-references**: split the docstrings for the + one-argument and two-argument `parameter` methods so their generated API + anchors can be resolved independently by downstream documentation. + +### ✅ Compatibility + +- **No breaking changes**: documentation and generated API anchors only; no + public signature, behavior, type, or name changed. No migration required. + ## [0.30.1-beta] - unreleased ### ✨ Added diff --git a/Project.toml b/Project.toml index 04c13f10..2860b494 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "CTBase" uuid = "54762871-cc72-4466-b8e8-f6c8b58076cd" -version = "0.30.1-beta" +version = "0.30.2-beta" authors = ["Olivier Cots ", "Jean-Baptiste Caillau "] [deps] diff --git a/src/Strategies/contract/abstract_strategy.jl b/src/Strategies/contract/abstract_strategy.jl index f488eacf..84f009b3 100644 --- a/src/Strategies/contract/abstract_strategy.jl +++ b/src/Strategies/contract/abstract_strategy.jl @@ -189,48 +189,6 @@ StrategyMetadata with option definitions for max_iter, etc. """ function metadata end -""" -$(TYPEDSIGNATURES) - -Return the strategy parameter type for a concrete strategy type, or `nothing` if the -strategy is non-parameterized. - -Every concrete strategy type must implement this method: -- Non-parameterized strategies return `nothing`. -- Parameterized strategies return the concrete parameter type. - -# Arguments -- `strategy_type::Type{<:AbstractStrategy}`: The strategy type - -# Returns -- `Type{<:AbstractStrategyParameter}`: The parameter type (e.g. `CPU`, `GPU`) -- `Nothing`: If the strategy is non-parameterized - -# Example -```julia-repl -# Non-parameterized: -julia> parameter(Ipopt) -nothing - -# Parameterized: -julia> parameter(MadNLP{CPU}) -CPU -``` - -# Implementation -```julia -# Non-parameterized strategy: -Strategies.parameter(::Type{<:MyStrategy}) = nothing - -# Parameterized strategy (bound repeated verbatim from the struct definition): -Strategies.parameter(::Type{<:MyStrategy{P}}) where {P<:AbstractStrategyParameter} = P -``` - -A non-throwing 2-arg variant, `parameter(strategy_type, default)`, is also available for -callers that cannot guarantee the type they're querying implements this contract — see below. - -See also: [`CTBase.Strategies.default_parameter`](@extref), [`CTBase.Strategies.AbstractStrategyParameter`](@extref) -""" function parameter end # ============================================================================ @@ -286,15 +244,46 @@ function metadata(::Type{T}) where {T<:AbstractStrategy} end """ -Default implementation for `parameter(::Type{T})` that throws `NotImplemented`. +$(TYPEDSIGNATURES) + +Return the strategy parameter type for a concrete strategy type, or `nothing` if the +strategy is non-parameterized. -Every concrete strategy must override this with either -`parameter(::Type{<:S}) = nothing` (non-parameterized) or -`parameter(::Type{<:S{P}}) where {P<:AbstractStrategyParameter} = P` (parameterized). +Every concrete strategy type must implement this method: +- Non-parameterized strategies return `nothing`. +- Parameterized strategies return the concrete parameter type. + +# Arguments +- `strategy_type::Type{<:AbstractStrategy}`: The strategy type + +# Returns +- `Type{<:AbstractStrategyParameter}`: The parameter type (e.g. `CPU`, `GPU`) +- `Nothing`: If the strategy is non-parameterized # Throws +- `Exceptions.NotImplemented`: When the concrete type doesn't override this method. -- `Exceptions.NotImplemented`: When the concrete type doesn't override this method +# Example +```julia-repl +# Non-parameterized: +julia> parameter(Ipopt) +nothing + +# Parameterized: +julia> parameter(MadNLP{CPU}) +CPU +``` + +# Implementation +```julia +# Non-parameterized strategy: +Strategies.parameter(::Type{<:MyStrategy}) = nothing + +# Parameterized strategy (bound repeated verbatim from the struct definition): +Strategies.parameter(::Type{<:MyStrategy{P}}) where {P<:AbstractStrategyParameter} = P +``` + +See also: [`CTBase.Strategies.default_parameter`](@extref), [`CTBase.Strategies.AbstractStrategyParameter`](@extref) """ function parameter(::Type{T}) where {T<:AbstractStrategy} return throw(