Adopt the SciML Style Guide for Julia Base and Standard Library?

[langestefan]

@csvance

I’m not sure if its just because I have not dug deep enough in Documenter.jl or not, but at a surface level I didn’t notice a way to neatly document arguments and return types following the Documenter.jl guide.

It’s all handwritten markdown right now, and there is no single agreed upon format to document function arguments. That’s why, in my opinion, Julia API docs can feel quite messy. Each project does it differently. I frequently run into API docs that haven’t documented function arguments at all, and everything is just Any according to the docs (but it never is)

I did some digging a while back and found this relevant discussion: Argument-specific docstrings or comments, unfortunately that never got any followup.

So for now my suggestion would be to:

1. Pick a style guide you like. SciML, Blue, YAS.
2. Ensure you follow the styleguide by using JuliaFormatter.jl
3. Apply style-specific formatting using custom CSS.