Skip to content

Declare documented API public (unlock downstream ExplicitImports)#491

Merged
ChrisRackauckas merged 1 commit into
JuliaArrays:masterfrom
ChrisRackauckas-Claude:declare-documented-api-public
Jun 26, 2026
Merged

Declare documented API public (unlock downstream ExplicitImports)#491
ChrisRackauckas merged 1 commit into
JuliaArrays:masterfrom
ChrisRackauckas-Claude:declare-documented-api-public

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown

Please ignore this PR until reviewed by @ChrisRackauckas. Opened at @ChrisRackauckas's request (a maintainer/top-contributor of ArrayInterface).

What

ArrayInterface exports nothing — its entire user-facing API is reached via ArrayInterface.foo. As a result, downstream packages must maintain ExplicitImports non-public allow-lists for names that are documented API but were never declared public. For example, SciMLStructures.jl#71 ignores restructure and has_trivial_array_constructor, noting they are "documented API but ArrayInterface has not adopted the public keyword."

This PR declares every documented, ArrayInterface-owned API name with the Julia 1.11+ public keyword so downstream packages (SciMLStructures, NonlinearSolve, and others) can drop those allow-lists.

The declaration is version-gated (@static if VERSION >= v"1.11.0-DEV.469") and eval'd via Expr(:public, ...) because the public keyword only parses on Julia 1.11+, while the package's compat floor is Julia 1.10.

Selection criteria

A name was made public iff it (a) carries a docstring in src/, (b) appears in the docs/src/*.md API pages, (c) is defined in ArrayInterface (not a re-export), and (d) is not already exported. The docstring set and the docs-page set were cross-referenced and match exactly (42 names). Internal helpers (underscore-prefixed, parameterless_type, stride_preserving_index, the index/device structs and type aliases, etc.) and the StaticArrayInterface-only names (known_*, stride_rank, contiguous_axis, …, which live in a separate package) were left non-public.

madePublic (42)

  • conversions (docs/src/conversions.md): aos_to_soa, promote_eltype, restructure, safevec, has_trivial_array_constructor
  • indexing traits (docs/src/indexing.md): can_avx, can_change_size, can_setindex, fast_scalar_indexing, ismutable, ndims_index, ndims_shape, defines_strides, ensures_all_unique, ensures_sorted, indices_do_not_alias, instances_do_not_alias, device
  • allowed indexing: allowed_getindex, allowed_setindex!
  • indexing type buffers: ArrayIndex, GetIndex, SetIndex!
  • linear algebra (docs/src/linearalgebra.md): zeromatrix, undefmatrix, issingular, bunchkaufman_instance, cholesky_instance, ldlt_instance, lu_instance, qr_instance, svd_instance
  • sparse arrays (docs/src/sparsearrays.md): isstructured, findstructralnz, has_sparsestruct, fast_matrix_colors, matrix_colors
  • wrapping (docs/src/wrapping.md): is_forwarding_wrapper, buffer, parent_type
  • tuples (docs/src/tuples.md): flatten_tuples, map_tuple_type

skipped (with reason)

  • already exported — none; ArrayInterface exports nothing, so no name was both exported and public.
  • undocumented internal helpers (no docstring, not in docs): parameterless_type, __parameterless_type, stride_preserving_index (block-comment only, not a docstring), diaganyzero, noalloc_diag, _cycle, _device, _not_pointer, _new_field_positions, _fl1, _indices_do_not_alias, _defines_strides
  • internal types / aliases / consts (not in docs): VecAdjTrans, MatAdjTrans, UpTri, LoTri, MatrixIndex, VectorIndex, BidiagonalIndex, TridiagonalIndex, BandedMatrixIndex, ColoringAlgorithm, AbstractDevice, AbstractCPU, CPUPointer, CPUTuple, CPUIndex, CheckParent, GPU, DEFAULT_CHOLESKY_PIVOT
  • not defined here (live in StaticArrayInterface.jl): known_length, known_size, known_first, known_last, known_step, static_length, indices, offsets, strides, contiguous_axis, stride_rank, dense_dims — none of these exist in this package, so they were not invented.

Verification (run locally)

  • Julia 1.10 (compat floor): package precompiles and loads cleanly; the public block is correctly skipped (version gate is false).
  • Julia 1.12.6: package loads; for all 42 names Base.ispublic(ArrayInterface, name) == true and Base.isexported(ArrayInterface, name) == false. The two SciMLStructures motivators (restructure, has_trivial_array_constructor) are confirmed public. Sampled internals (parameterless_type, stride_preserving_index, MatrixIndex, BidiagonalIndex, CPUPointer, diaganyzero) confirmed to remain non-public.
  • Full test suite on Julia 1.10 passes (Core 195/195, AD Integration 20/20, StaticArrays 39/39, BandedMatrices 21/21, BlockBandedMatrices 8/8, ChainRules 20/20) — Aqua included.
  • Formatting: the added block matches the repo's .JuliaFormatter.toml SciML style (running the official formatter leaves the block unchanged); no bulk reformatting of unrelated code.

🤖 Generated with Claude Code

ArrayInterface exports nothing; all of its user-facing API is accessed via
`ArrayInterface.foo`. Downstream packages (SciMLStructures, NonlinearSolve, and
others) therefore have to maintain ExplicitImports non-public allow-lists for
names that are documented API but were never declared `public` (e.g.
SciMLStructures.jl#71 ignores `restructure` and `has_trivial_array_constructor`).

Declare every documented, ArrayInterface-owned API name (each carries a docstring
and appears in the docs/src/*.md API pages) with the `public` keyword so those
allow-lists can be dropped. The declaration is version-gated and `eval`'d because
`public` only parses on Julia 1.11+ while the package floor is 1.10.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@codecov

codecov Bot commented Jun 25, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.20%. Comparing base (83d7bc9) to head (62cb429).

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #491   +/-   ##
=======================================
  Coverage   60.20%   60.20%           
=======================================
  Files          14       14           
  Lines         588      588           
=======================================
  Hits          354      354           
  Misses        234      234           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ChrisRackauckas ChrisRackauckas marked this pull request as ready for review June 26, 2026 00:43
@ChrisRackauckas ChrisRackauckas merged commit c00103e into JuliaArrays:master Jun 26, 2026
17 of 21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants