Edit: tldr, Julia could use something with the ease of use and functionality of docs.rs, but built especially with Julia's typesystem in mind.
So after thinking about this, I think there are two things going on here. 1) it's actually the lack of browsable autogenerated API docs I'm frustrated by... I'm spoiled by the most excellent Rust docs.rs API docs, which give a great, quick, readable, comprehensive overview of what's in a package even if the maintainer hasn't made any docstrings and (2) rust has had this emphasis on usable documentation as a seamless part of the development experience for a while, but Julia is definitely catching up.
So I went back and checked and was happy to find that the JuliaGPU packages that I previously couldn't find docs for definitely have some docs now! In particular, GPUArrays.jl. There were also some astronomy packages I looked at had been rewritten with docs left hanging for like a year.
That said, in the autogenerated API docs for GPUArrays.jl, if there's a function with no docstrings, on JuliaHub it just shows a big yellow warning to the developer. I'd prefer if it showed some useful information about the types the function is defined over and its return types. I'd also love if there was some quick way to see a list of included types and functions, along with their type signature and even a way to view the code.
Really I think I'm just spoiled by the Rust community's amazing auto-generated API docs on docs.rs, which seamlessly integrate with examples and readme style docs. If there's a rust package I wanna use, docs.rs will give me a nice consistent, browsable overview of the code and I can usually figure out what's in there just from that, even if the package maintainer hasn't actually written any example docs or docstrings, just using info from the typesystem. It's so nice to be able to go to one place and see what's in a package, the traits, structs and function signatures, all alongside docs generated from docstrings and handwritten docs. Did I mention that this information is always in the same place on docs.rs? These aren't just "filler" docs, they're super usable.
Most Julia package docs are more freeform and I have to click around to find the API docs, and honestly I'm not sure if every package even has these. Whereas on docs.rs they're right there immediately with no cognitive overhead. Freeform docs are awesome, and I'm always excited when a package has lots of well thought out documentation, but it's no substitute for up to date, informative API docs that give you a solid window into the fundamentals and interfaces.
Julia has such a cool typesystem, I could imagine there are some interesting opportunities to use that to make the autogenerated Julia docs much more usable and informative.
As far as the comprehensive approach is concerned, I honestly don't think Julia is that far off, it's really a shift in emphasis and a streamlining that I'm wishing for. I can see that a lot of progress has been made.
Maybe it'd be worthwhile to consider hiring some of those ex-Mozilla people to help the Julia community get to the next level on this?
So after thinking about this, I think there are two things going on here. 1) it's actually the lack of browsable autogenerated API docs I'm frustrated by... I'm spoiled by the most excellent Rust docs.rs API docs, which give a great, quick, readable, comprehensive overview of what's in a package even if the maintainer hasn't made any docstrings and (2) rust has had this emphasis on usable documentation as a seamless part of the development experience for a while, but Julia is definitely catching up.
So I went back and checked and was happy to find that the JuliaGPU packages that I previously couldn't find docs for definitely have some docs now! In particular, GPUArrays.jl. There were also some astronomy packages I looked at had been rewritten with docs left hanging for like a year.
That said, in the autogenerated API docs for GPUArrays.jl, if there's a function with no docstrings, on JuliaHub it just shows a big yellow warning to the developer. I'd prefer if it showed some useful information about the types the function is defined over and its return types. I'd also love if there was some quick way to see a list of included types and functions, along with their type signature and even a way to view the code.
Really I think I'm just spoiled by the Rust community's amazing auto-generated API docs on docs.rs, which seamlessly integrate with examples and readme style docs. If there's a rust package I wanna use, docs.rs will give me a nice consistent, browsable overview of the code and I can usually figure out what's in there just from that, even if the package maintainer hasn't actually written any example docs or docstrings, just using info from the typesystem. It's so nice to be able to go to one place and see what's in a package, the traits, structs and function signatures, all alongside docs generated from docstrings and handwritten docs. Did I mention that this information is always in the same place on docs.rs? These aren't just "filler" docs, they're super usable.
Most Julia package docs are more freeform and I have to click around to find the API docs, and honestly I'm not sure if every package even has these. Whereas on docs.rs they're right there immediately with no cognitive overhead. Freeform docs are awesome, and I'm always excited when a package has lots of well thought out documentation, but it's no substitute for up to date, informative API docs that give you a solid window into the fundamentals and interfaces.
Julia has such a cool typesystem, I could imagine there are some interesting opportunities to use that to make the autogenerated Julia docs much more usable and informative.
As far as the comprehensive approach is concerned, I honestly don't think Julia is that far off, it's really a shift in emphasis and a streamlining that I'm wishing for. I can see that a lot of progress has been made.
Maybe it'd be worthwhile to consider hiring some of those ex-Mozilla people to help the Julia community get to the next level on this?