[joshlemer]

Along the same lines with the docs, I also find it frustrating that a lot of the very most core basic abstractions and interfaces are left totally undefined in terms of documentation. Take `ISeq`'s definition. Surely, a candidate for the single most core interface.

https://github.com/clojure/clojure/blob/master/src/jvm/cloju...

But like, where is the javadoc? What exactly is supposed to be the contract of these methods `first`, `next`, `more`, `cons`? What's the difference between `next` and `more`?

I really just don't like that. Are we just supposed to pick up the core contracts/abstractions through oral teachings and slack channel messages?

[puredanger]

You don’t use the ISeq interface directly, you use them through the clojure.core API. The seq abstraction is documented at https://clojure.org/reference/sequences

[joshlemer]

It’s rare for an application developer to need to use ISeq, but library authors do use of when they want to implement custom seq’s right? For them, and also just for those curious to understand how the core interfaces work, it’s still better to be explicit and write what the contract is I reckon.

[puredanger]

Generally, custom seqs (rare) are implemented by leveraging something like `lazy-seq`, so library authors are also not using it.

Yes, it would be good if there were javadoc on more of the impl, but this is just not an issue for the vast majority of devs.