Is clojure.lang really just implementation details?

Question

In Clojure, some tasks (such as instantiating a PersistentQueue or using deftype to implement a custom data type that is compatible with the clojure.core functions) require knowledge of the classes and/or interfaces in clojure.lang.

However, according to clojure.lang/package.html:

The only class considered part of the public API is clojure.lang.IFn. All other classes should be considered implementation details.

Are these statements incorrect or outdated? If so, are there plans to correct them in the future? If not, is there a more preferred way to perform the tasks mentioned above, or should they simply not be done at all in idiomatic Clojure code?

Answer 1

Alex Miller has commented on this in the past (the whole thread is worth reading though):

I'd say there is a range of "public"-ness to the internals of Clojure.

• The new Clojure API (clojure.java.api.Clojure) is an official public API for external callers of Clojure. This API basically consists of ways to resolve vars and invoke functions.
• For Clojure users in Clojure, pretty much any var that's public and has a docstring, and shows up in the api docs can be considered public API.
• Clojure vars that are private or have no docstring (such that the var is omitted from public api docs) are likely places to tread very carefully.
• The Clojure internal Java interfaces [clojure.lang] are certainly intended to allow library builders to create useful stuff that plays in the Clojure world. I do not know that anyone has ever said that they are "public", but I certainly think that any change to a core interface likely to break external users would be considered very carefully.
• The Clojure internal Java classes [clojure.lang] should in most cases be considered private and subject to change without notice. There are grey areas even there.

In general, we do not place a high value on encapsulation or hiding internals. In most cases, the internals are left available if they might be useful to an advanced user doing interesting things, with the caveat that the weirder things you do, the more likely you are to be accidentally broken in a future release.