Updated documentation

Author: Shuvomoy

.gitignore

@@ -11,3 +11,4 @@ tutorials/.DS_Store
 /docs/src/generated_examples/
 /docs/src/examples.md
 /docs/src/changelog.md
+/gitignore-folder

CHANGELOG.md

@@ -6,6 +6,42 @@ project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html
 
 ## [Unreleased]
 
+### Added
+- Mathematical interpolation conditions (in display-math fences, verified
+  against each `add_class_constraints!` implementation) in the docstrings of
+  all 16 function classes and 13 operator classes.
+- Academic references in all function/operator class docstrings, ported from
+  the corresponding Python PEPit docstrings (Taylor-Hendrickx-Glineur,
+  Ryu-Taylor-Bergeling-Giselsson, Bousselmi-Hendrickx-Glineur,
+  Bauschke-Combettes, and others).
+- Class-specific notes ported from Python PEPit: differentiability and
+  `reuse_gradient` behavior, `L == Inf`/`beta == 0` degenerate-parameter
+  advice, the nonexpansive infimal-displacement-vector discussion, and the
+  documented adjoint usage `gradient!(M.T, u)` for `LinearOperator`.
+- A representative `# Returns approximately: (...)` output line inside the
+  `# Julia usage` block of every example docstring (96 examples), generated by
+  running each example with its documented arguments (Clarabel).
+
+### Fixed
+- Class docstring usage examples previously showed the template placeholder
+  `OrderedDict("L" => 1.0)  # adapt keys to the class` for every class; each
+  class now shows its actual parameter keys (`"mu"`, `"beta"`, `"M"`, `"rho"`,
+  `"partition"`, ...), so copy-pasting no longer raises `KeyError`.
+- Mislabeled prose in operator docstrings: `LipschitzOperator` and both
+  `CocoerciveStronglyMonotoneOperator*` variants described "Cocoercive
+  operators"; `BlockSmoothConvexFunctionExpensive` referred to itself by a
+  non-existent name (`RefinedBlockSmoothConvexFunctionExpensive`).
+- Ten example docstrings falsely claimed "No bibliographic reference was
+  listed in the corresponding Python PEPit example docstring"; eight now carry
+  the actual references (Lieder; Gu-Yang; Kim; Park-Ryu; Bousselmi et al.;
+  Goujaud et al.) and the remaining two state that no reference exists.
+- Broken display-math fence in the theoretical-guarantee block of
+  `examples/fixed_point_problems/krasnoselskii_mann_constant_step_sizes.jl`.
+- `# Note`/`# Warning` pseudo-headings with indented bodies in class
+  docstrings (rendered as code blocks by Documenter) replaced with proper
+  `!!! note`/`!!! warning` admonitions; generic `# Fields` boilerplate
+  replaced with accurate per-class field descriptions.
+
 ## [0.1.2] - 2026-06-08
 
 ### Added

examples/adaptive_methods/polyak_steps_in_distance_to_optimum.jl

@@ -83,6 +83,7 @@ In Conference on Learning Theory (COLT).](https://arxiv.org/pdf/2002.00915.pdf)
 # Julia usage
 ```julia
 pepit_tau, theoretical_tau = wc_polyak_steps_in_distance_to_optimum(1.0, 0.1, 2 / (1.0 + 0.1); solver=Clarabel.Optimizer, verbose=true)
+# Returns approximately: (pepit_tau, theoretical_tau) = (0.669421, 0.669421)
 ```
 """
 function wc_polyak_steps_in_distance_to_optimum(L, mu, gamma; solver=Clarabel.Optimizer, verbose=true)

examples/adaptive_methods/polyak_steps_in_function_value.jl

@@ -83,6 +83,7 @@ In Conference on Learning Theory (COLT).](https://arxiv.org/pdf/2002.00915.pdf)
 # Julia usage
 ```julia
 pepit_tau, theoretical_tau = wc_polyak_steps_in_function_value(1.0, 0.1, 2 / (1 + 0.1); verbose=true)
+# Returns approximately: (pepit_tau, theoretical_tau) = (0.669421, 0.669421)
 ```
 """
 function wc_polyak_steps_in_function_value(L, mu, gamma; verbose=true)

examples/composite_convex_minimization/accelerated_douglas_rachford_splitting.jl

@@ -87,6 +87,7 @@ In 53rd IEEE Conference on Decision and Control (CDC).](https://arxiv.org/pdf/14
 # Julia usage
 ```julia
 pepit_tau, theoretical_tau = wc_accelerated_douglas_rachford_splitting(0.1, 1.0, 0.9, 2; verbose=true)
+# Returns approximately: (pepit_tau, theoretical_tau) = (0.192915, 1.688889)
 ```
 """
 function wc_accelerated_douglas_rachford_splitting(mu, L, alpha, n; solver=Clarabel.Optimizer, verbose=true)

examples/composite_convex_minimization/accelerated_proximal_gradient.jl

@@ -72,6 +72,7 @@ SIAM journal on imaging sciences, 2009, vol. 2, no 1, p. 183-202.](https://www.c
 # Julia usage
 ```julia
 pepit_tau, theoretical_tau = wc_accelerated_proximal_gradient(0.0, 1.0, 4; solver=Clarabel.Optimizer, verbose=true)
+# Returns approximately: (pepit_tau, theoretical_tau) = (0.051673, 0.066126)
 ```
 """
 function wc_accelerated_proximal_gradient(mu, L, n; solver=Clarabel.Optimizer, verbose=true)

examples/composite_convex_minimization/accelerated_proximal_gradient_simplified.jl

@@ -76,6 +76,7 @@ SIAM Journal on Optimization, 27(3):1283-1313.](https://arxiv.org/pdf/1512.07516
 # Julia usage
 ```julia
 pepit_tau, theoretical_tau = wc_accelerated_proximal_gradient_simplified(0.0, 1.0, 4; verbose=true)
+# Returns approximately: (pepit_tau, theoretical_tau) = (0.052632, 0.052632)
 ```
 """
 function wc_accelerated_proximal_gradient_simplified(mu, L, n; solver=Clarabel.Optimizer, verbose=true)

examples/composite_convex_minimization/bregman_proximal_point.jl

@@ -64,6 +64,7 @@ Journal of Optimization Theory and Applications, 73(3), 451-464.](https://link.s
 # Julia usage
 ```julia
 PEPit_tau, theoretical_tau = wc_bregman_proximal_point(3.0, 5; verbose=true)
+# Returns approximately: (PEPit_tau, theoretical_tau) = (0.066667, 0.066667)
 ```
 """
 function wc_bregman_proximal_point(gamma, n; verbose=true)

examples/composite_convex_minimization/douglas_rachford_splitting.jl

@@ -78,6 +78,7 @@ In 56th IEEE Conference on Decision and Control (CDC).](https://github.com/Adrie
 # Julia usage
 ```julia
 PEPit_tau, theoretical_tau = wc_douglas_rachford_splitting(1.0, 1.0, 1.0, 9; verbose=true)
+# Returns approximately: (PEPit_tau, theoretical_tau) = (0.027792, 0.0278)
 ```
 """
 function wc_douglas_rachford_splitting(L, alpha, theta, n; verbose=true)

examples/composite_convex_minimization/douglas_rachford_splitting_contraction.jl

@@ -88,6 +88,7 @@ Applied and Computational Mathematics 15(1), 3-43.](https://web.stanford.edu/~bo
 # Julia usage
 ```julia
 PEPit_tau, theoretical_tau = wc_douglas_rachford_splitting_contraction(0.1, 1.0, 3.0, 1.0, 2; verbose=true)
+# Returns approximately: (PEPit_tau, theoretical_tau) = (0.350128, 0.350128)
 ```
 """
 function wc_douglas_rachford_splitting_contraction(mu, L, alpha, theta, n; verbose=true)