I’m new to Julia and try to use different packages.I find it hard to use the documentation (when it exists). I appreachiate all descriptions and examples and everything in the docs, but I miss pages like “Here is type X and here are all the methods that take a parameter of this type. Also, X is a subtype of Y and is supertype of A and B.”
Example: In Meshes.jl there exist a type SimpleMesh which is a subtype of Mesh. This information is not very prominent on the page (yes it is in the description at the top, but it is not mentioned in the boxes for the types themselves.) Also stuff like "You can call the method vertices with a Mesh as parameter is missing
I didn’t find something like this. Is it not something that most people woud like to use? Do I “program the wrong way”?
I’m not sure how easy that would be generalized into improvements for Documenter.jl. I’m sure @docs/@autodocs could be improved, or additional syntax (like this one) could be introduced.
To some extent, Julia’s flexibility works against automatic API documentation, compared to, e.g., Java, where javadoc can generate very complete information, due to Java’s very strict object-oriented philosophy. Julia is much more messy, and thus requires more human judgement when writing API documentation.
In any case, there’s nothing wrong with your desire for good API documentation. Realistically, though, the only thing to do is to put in the effort for the documentation of your own packages, and maybe contribute to the documentation of existing packages where you can.
This is possible to do, but would require different tooling than is currently in widespread use by the community. For example, https://fluxml.ai/FastAI.jl uses https://lorenzoh.github.io/Pollen.jl, which handles API reference documentation a good bit better than the status quo. The bigger problem IMO is that there are only X number of dev hours these days to work on documentation, and most of those are necessarily put towards maintaining systems like Documentor instead of experimenting with/developing new ideas.
One wonders if this would be a good place to attract new contributions, as working on a docs system doesn’t require any specialist knowledge in particular scientific/numeric domains. That said, I do agree that the relative scarcity of static type information in a lot of Julia code makes something around the level of JavaDoc/RustDoc difficult.
One of my current long-term goals with Documenter maintenance is to make it more plugin-friendly, so that it would be possible to experiment with ideas within Documenter, and not having to re-invent a whole new package to try out one idea. But this itself is a pretty large maintenance / refactoring task.
The Pollen-like autogenerated reference pages for objects (e.g. stuff like full method lists etc) is something that I have always wanted to experiment with in Documenter (it was actually in my first GSoC proposal). I just haven’t found the time to play with the idea yet. It would be a great project for a Documenter plugin though if anyone wants to tackle it (and maybe could also share some code with Pollen here).
Thank you for all your answers! I’ll have a look at the different provided links. And if I develop a package I’ll try my best to provide good documentation
Thanks for pointing out why documentation like this is rare (limited time obviously, but also different handling of types in Julia)