How do you actually find out *how* to use an interface in Julia, like the concept of iterator "end"?

[mkitti]

@teacup775

The smart alec way I would describe it is that JL documentation is orthogonal to almost all my expectations. With every other language I have worked with the chief advantage in beauty of Java was that the language designers decided to include a very direct template for class documentation for the fields for the methods for the arguments of the methods and an entire system that was used to generate a useful documentation tree so people could understand abstractions down to their implementations all provided there. I should know I worked with some of the principal people who developed the language. They put a lot of thought into this into making the programming environment of Java, deliberately accessible to what they would call the average programmer.

I personally find the Java documentation particularly obtuse for newcomers as I illustrated above, but I know my way around it from experience. In particular, I know Java and C++ are object oriented so I might expect an abstract base class or formal interface.

Part of the difference in expectation here is that Julia does not implement an object oriented programming paradigm. We have a multiple dispatch paradigm which shifts the conceptual emphasis to verbs (i.e. iterate) rather than nouns (i.e. Iterator). The approach here is in fact orthogonal and that is reflected in the documentation.

I think part of your frustration originates from having particular experience with other languages and expecting Julia to be the same. I work in an environment that uses both Java and Python heavily among other languages. While I appreciate that JavaDoc follows a particularly pattern that I familiar with, I see my junior colleagues struggle with this pattern. Thus, I’m not particularly convinced that Java is the best example here. It’s helpful to you and I because we are familiar with the language, but others who are not familiar with Java would struggle with it just as you are struggling with the Julia documentation.

Perhaps one thing to take away from JavaDoc is having some regular structure to Julia docstrings. What pattern should arguments follow in implementing methods? What return type is expected? Is this function part of a larger interface?

From your elaboration, I see that your main interface here is to use search. Alternatives might be using the Table of Contents or using a LLM. This is helpful and thus I can formulate some concrete action items.

1. We have a module called Base.Iterators that people may land upon when searching for items. Modules should contain some documentation and link to the Iteration Interface section: julia/doc/src/base/iterators.md at master · JuliaLang/julia · GitHub
2. While Iteration Interface is referred to in the section introduction above where Base.iterate documented, it is not referred to within the docstring for iterate itself. We should refer to interfaces in the docstrings of functions belonging to those interfaces: julia/base/essentials.jl at 966d0af0fdffc727eb240e2e4c908fdd46697e57 · JuliaLang/julia · GitHub
3. Search should emphasize headings in the Essentials and Manual sections. Search should also expand nouns to their analogous verbs (e.g. “Iterator” => “iterate” or “iteration”).
4. We may need an explicit comparison between object orientation and multiple dispatch in the manual perhaps with an emphasis on interfaces.

Thank you. Let me see if we can make progress on some of these action items.