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 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 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. Re documentation, I personally would like to have more around the Java interfaces, but I don't know whether that will happen. I think 80% of the interfaces are pretty obvious but admittedly that last 20% can take a while to ferret out. I'm happy to answer questions as I see them on the list. On Tuesday, February 11, 2014 5:02:16 PM UTC-6, John Hume wrote: > > On Tue, Feb 11, 2014 at 7:32 AM, Phillip Lord > <philli...@newcastle.ac.uk<javascript:> > > wrote: > >> "John D. Hume" <duelin....@gmail.com <javascript:>> writes: >> > Other than the new (and quite minimal) Java API for calling >> > Clojure code[1], the details of Clojure's underlying Java classes are >> > considered implementation details and could change from release to >> release >> > without being considered a breaking change. >> >> >> And the interfaces? I mean, ISeq is defines the sequence abstraction. > > > When I said "underlying java classes" I meant "underlying Java classes and > interfaces." > > Although there are contrib and third party libraries that depend on these > implementation details, I think the message to the community at large has > always been not to depend on them, and as far as I know, the maintainers > have not committed to keeping anything other than the newly documented Java > API and the existing Clojure API in Clojure stable. > > So if I'm not mistaken, in spite of the fact that you can find many > examples of people doing it, there is no blessed way to create custom > Clojure data structures (unless you count defrecord) and no official > documentation to encourage or assist you. > > Hopefully I am mistaken, or this will change someday soon. :) > > -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
