I’m trying to document my Julia packages not necessarily to the style of Base, but so that it communicates the ideas fast to serious users who have a basic training with Julia but have prior programming or even software development experience. Please let me know below how you’d document the following:
Suppose you have a Holy-trait, which I understand is a data type that triggers different types of dispatch
abstract type ConstraintType end struct NoConstraints <: ConstraintType end struct AffineConstraints <: ConstraintType end struct BoxConstraints <: end function runsolver(c::ConstraintType, other_stuff...) runspecializedsolver(c, other_stuff...) end function runspecializedsolver(c::BoxConstraints, other_stuff...) # code. end function runspecializedsolver(c::NoConstraints, other_stuff...) # code. end
I used to not include the types here in the public API when I use Documenter.jl to build the docs. However, in cases like this one, the user of this package might actually need to know what
ConstraintType is, because it is mentioned in the documentation of
runsolver()s public API. In this case, I’d like to at least explain that
ConstraintType is a supertype of
BoxConstraints, and one should really call
AffineConstraints in their code before they call
I’ve resorted to just doing
""" abstract type ConstraintType end """ abstract type ConstraintType end # etc.
for all the types, which is quite a bit of boiler plate documentation code. I understand Julia users can always just do
?ConstraintType in the Julia REPL and get equivalent auto-generated like the ones I’m using, but this would not make it to the public API page generated by Documenter.jl.
I’m interested in hearing what others here would do.