Действительно ли clojure.lang действительно детали реализации?

Question

В Clojure некоторые задачи (например, создание экземпляра PersistentQueue или использование deftype для реализации пользовательского типа данных, совместимого с функциями clojure.core) требуют знания классов и/или интерфейсов в clojure.lang.

Однако, по словам clojure.lang/package.html:

Единственный класс рассматривается как часть общественного API является clojure.lang.IFn. Все остальные классы должны рассматриваться как детали реализации.

Являются ли эти утверждения неправильными или устаревшими? Если да, планируют ли они исправить их в будущем? Если нет, есть ли более предпочтительный способ выполнения упомянутых выше задач, или они просто не будут выполняться вообще в идиоматическом коде Clojure?

Answer 1

Алекс Миллер commented на это в прошлом (весь поток стоит читать, хотя):

Я бы сказал, что существует целый ряд «общественного» -ness к внутренностям Clojure.

• Новый API Clojure (clojure.java.api.Clojure) является официальным публичным API для внешних абонентов Clojure. Этот API в основном состоит из способов решения vars и вызова функций.
• Для пользователей Clojure в Clojure, почти любой публичный var, имеющий docstring и отображаемый в api docs, может считаться открытым API.
• Clojure vars, которые являются частными или не имеют docstring (такие, что var опущен из общедоступных api docs), вероятно, являются местами для протектора очень осторожно.
• Внутренние интерфейсы Java Clojure [clojure.lang], безусловно, предназначены для того, чтобы позволить сборщикам библиотек создавать полезные материалы, которые играют в мире Clojure. Я не знаю, что кто-либо когда-либо говорил, что они «публичные», но я, конечно, считаю, что любое изменение основного интерфейса, которое может нарушить внешних пользователей, будет считаться очень осторожным.
• Внутренние классы Java Clojure [clojure.lang] должны в большинстве случаев считаться конфиденциальными и могут быть изменены без предварительного уведомления. Там есть серые области.

В целом мы не придаем большое значение инкапсуляции или скрытию внутренних элементов. В большинстве случаев внутренности остаются доступными, если они могут быть полезны для продвинутого пользователя, занимающегося интересными вещами, с оговоркой, что более странные вещи вы делаете, тем более вероятно, что вы случайно будете разбиты в будущей версии.