Skip to content

Commit 07e3a76

Browse files
Merge pull request #136 from ChrisRackauckas-Claude/add-missing-docstrings
Add comprehensive docstrings for cache functions
2 parents 0b48f9c + 5a76d91 commit 07e3a76

File tree

3 files changed

+56
-1
lines changed

3 files changed

+56
-1
lines changed

docs/pages.jl

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
# Put in a separate page so it can be used by SciMLDocs.jl
22

3-
pages = ["Home" => "index.md", "preallocationtools.md"]
3+
pages = ["Home" => "index.md",
4+
"API" => "preallocationtools.md",
5+
"Internals" => "internals.md"]

docs/src/internals.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Internal Functions
2+
3+
This page documents internal functions that are not part of the public API but may be encountered during debugging or when extending PreallocationTools.jl functionality.
4+
5+
!!! warning
6+
These are internal implementation details and may change without notice in any release. They should not be relied upon for user code.
7+
8+
## Cache Management Functions
9+
10+
```@docs
11+
PreallocationTools.get_tmp(::FixedSizeDiffCache, ::Union{Number, AbstractArray})
12+
PreallocationTools.get_tmp(::FixedSizeDiffCache, ::Type{T}) where {T <: Number}
13+
PreallocationTools.get_tmp(::DiffCache, ::Union{Number, AbstractArray})
14+
PreallocationTools.get_tmp(::DiffCache, ::Type{T}) where {T <: Number}
15+
PreallocationTools.enlargediffcache!
16+
```
17+
18+
## Internal Helper Functions
19+
20+
```@docs
21+
PreallocationTools._restructure
22+
```

src/PreallocationTools.jl

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,18 @@ chunksize(::Type{T}) where {T} = 0
4444

4545
# ForwardDiff-specific methods moved to extension
4646

47+
"""
48+
get_tmp(dc::FixedSizeDiffCache, u::Union{Number, AbstractArray})
49+
50+
Returns the appropriate cache array from the `FixedSizeDiffCache` based on the type of `u`.
51+
52+
If `u` is a regular array or number, returns the standard cache `dc.du`. If `u` contains
53+
dual numbers (e.g., from ForwardDiff.jl), returns the dual cache array. The function
54+
automatically handles type promotion and resizing of internal caches as needed.
55+
56+
This function enables seamless switching between regular and automatic differentiation
57+
computations without manual cache management.
58+
"""
4759
function get_tmp(dc::FixedSizeDiffCache, u::Union{Number, AbstractArray})
4860
if promote_type(eltype(dc.du), eltype(u)) <: eltype(dc.du)
4961
dc.du
@@ -148,6 +160,25 @@ function _restructure(normal_cache::AbstractArray, duals)
148160
ArrayInterface.restructure(normal_cache, duals)
149161
end
150162

163+
"""
164+
enlargediffcache!(dc::DiffCache, nelem::Integer)
165+
166+
Enlarges the dual cache array in a `DiffCache` when it's found to be too small.
167+
168+
This function is called internally when automatic differentiation requires a larger
169+
dual cache than initially allocated. It resizes `dc.dual_du` to accommodate `nelem`
170+
elements and issues a one-time warning suggesting an appropriate chunk size for
171+
optimal performance.
172+
173+
## Arguments
174+
- `dc`: The `DiffCache` object to enlarge
175+
- `nelem`: The new required number of elements
176+
177+
## Notes
178+
The warning is shown only once per `DiffCache` instance to avoid spam. For optimal
179+
performance in production code, pre-allocate with the suggested chunk size to avoid
180+
runtime allocations.
181+
"""
151182
function enlargediffcache!(dc, nelem) #warning comes only once per DiffCache.
152183
chunksize = div(nelem, length(dc.du)) - 1
153184
@warn "The supplied DiffCache was too small and was enlarged. This incurs allocations

0 commit comments

Comments
 (0)