Skip to content

Document public API coverage gaps#4715

Draft
ChrisRackauckas-Claude wants to merge 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:agent/public-api-docs-coverage
Draft

Document public API coverage gaps#4715
ChrisRackauckas-Claude wants to merge 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:agent/public-api-docs-coverage

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor

This PR should be ignored until reviewed by @ChrisRackauckas.

Summary

  • Adds docstrings at original definitions where practical for public/exported ModelingToolkit and ModelingToolkitBase API gaps found by the audit.
  • Expands several existing docstrings into SciMLStyle-style entries with signatures, arguments, returns, examples, and cross references.
  • Adds rendered docs entries for newly documented public API in user API pages and developer-facing structural transformation internals.
  • Replaces the @deprecate structural_simplify forms with explicit deprecated wrapper methods so the deprecated API can carry a docstring at its definition point.

Local validation

  • Runic.jl passed on all touched Julia files:
    timeout 3600 /home/crackauc/.juliaup/bin/julia +release --startup-file=no -e 'using Pkg; Pkg.activate(; temp=true); Pkg.add("Runic"); using Runic; exit(Runic.main(ARGS))' -- --inplace ...
  • Load/precompile check passed:
    timeout 3600 /home/crackauc/.juliaup/bin/julia +release --startup-file=no --project=. -e 'using ModelingToolkitBase, ModelingToolkit; println("loaded ModelingToolkit ", pkgversion(ModelingToolkit))'
  • Current local public/exported doc audit after this patch:
    • ModelingToolkit: 16 remaining Docs.hasdoc gaps: @symbolic_wrap, @wrapped, D, DiscreteSystem, ImplicitDiscreteSystem, RuleSet, StructuralTransformations, TimeDomain, UnPack, get_canonical_expr, infimum, is_derivative, istree, solve_for, supremum, t.
    • ModelingToolkitBase: 15 remaining Docs.hasdoc gaps: @symbolic_wrap, @wrapped, D, DiscreteSystem, ImplicitDiscreteSystem, RuleSet, TimeDomain, UnPack, get_canonical_expr, infimum, is_derivative, istree, solve_for, supremum, t.
    • These residuals look like upstream reexports/compat names, generated deprecated aliases, and public-but-not-bound t/D aliases rather than locally owned undocumented definitions.

Blockers / incomplete validation

  • Full QA test command timed out after the required 1-hour shell timeout while still running ModelingToolkitBase/test/initializationsystem.jl; no pass is claimed:
    timeout 3600 /home/crackauc/.juliaup/bin/julia +release --startup-file=no --project=. -e 'using Pkg; Pkg.test(; test_args=["QA"])'
  • Local docs build with the checkout explicitly developed into the docs environment is blocked by dependency resolution before Documenter runs. The resolver conflict is OptimizationOptimJL 0.4 requiring Optim < 2 while the local stack resolves ForwardDiff 1, restricting Optim to versions that leave no compatible Optim candidate.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
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