Fork me on GitHub

Where do people put package-level documentation? Let's say I have an app with structure like:

- users
- admin
- plans
  - a.clj
  - b.clj
  - c.clj
Now I want to write some docs that apply to most of the things in the plans directory. E.g. In java, there's that can serve this purpose.

Alex Miller (Clojure team)12:11:43

Namespace metadata is probably the closest


@U064X3EF3 what do you mean by namespace metadata? I would put higher-level docs in ns docstring but here I'm asking about docs that apply to multiple namespaces.

Alex Miller (Clojure team)14:11:35

I meant ns docstring. there is no other place

Alex Miller (Clojure team)14:11:52

there's no equivalent of


Is it docs for developers? Because I've seen people just put a README in a directory before. I've also worked on a project that had an "adr" (Architecture Decision Record" directory that would have a markdown file that discusses a "package" of namespaces.


Yeah, is one alternative I considered

Dr. Moltu10:11:50

Hi, can anyone confirm that containsAll() implementation in PersistentQueue is not correct? thx

public boolean containsAll(Collection c) {
    for (Object o : c) {
        if (contains(o))
            return true;
    return false;


looks more like containsAny, yeah


I'm curious how did you find that 🙂

Dr. Moltu11:11:46

So I'm interested in persistent batched queues, while reading the Clojure implementation, I found it :D

Colin P. Hill13:11:36

Anyone have any examples of the queue usage patterns Rich is talking about He talks about how the queues in java.util.concurrent are underused, and suggests that this might be because he didn't wrap them (as they can be used in their native Java form). Checking git history, looks like this talk was 9 years after his first cut of clojure.lang.PersistentQueue, so it seems like he's talking about something other than this.

Colin P. Hill13:11:19

I can understand the principles of what he's saying and it makes good sense, but I'm having a hard time imagining how the plumbing fits together

Alex Miller (Clojure team)13:11:04

core.async incorporates a lot of these ideas

Alex Miller (Clojure team)13:11:22

PQ (being persistent) is not really relevant, since it's persistent (I rarely use it in anything other than a single-threaded context)

Alex Miller (Clojure team)13:11:07

the Deque / Transfer stuff in juc is probably the most interesting for the things he's talking about here, and core.async channels have a lot of the Transfer queue semantics

Colin P. Hill13:11:38

Oh, I was scouring the source of core.async for java.util.concurrent and then realized I might have misunderstood you – do you mean that core.async is essentially the Clojure equivalent he was saying hadn't yet (at this point) been written?

Alex Miller (Clojure team)13:11:22

I think the kernel of the ideas were probably there at that point

Colin P. Hill13:11:45

Got it. I'll look into guides on use of core.async then. Thank you!

Alex Miller (Clojure team)13:11:54

and eventually became core.async

Alex Miller (Clojure team)13:11:07

Clojure Applied has a couple chapters on core.async


I want to create something like a type alias for ExceptionInfo — i.e. a class that extends it but just slaps a new name on it and otherwise delegates everything to the original class. What's the easiest way to do this?

Alex Miller (Clojure team)14:11:22

the whole point of ExceptionInfo is it carries a data map that you can add additional information to


I'm interfacing with code written by others and I want to be able to throw something that acts exactly like an ExceptionInfo but has a different class name.


(so that calling code can catch this exception type and ExceptionInfo separately)


(I want it to work like ExceptionInfo because I like the way ExceptionInfo works)

Alex Miller (Clojure team)14:11:16

it's probably easier to re-implement IExceptionInfo and make a new type, than to proxy or subclass ExceptionInfo itself

Alex Miller (Clojure team)14:11:26

there's almost nothing in ExceptionInfo

Alex Miller (Clojure team)14:11:55

it's just an exception carrying a map

Noah Bogart14:11:06

i’ve been reading about protocols and how most of the clojure.core functions in the java implementation use interfaces whereas the javascript implementation use protocols. (see this discussion about nth for an example). i realize the reason clojure didn’t switch over at the release of 1.2 was backwards compatibility and we’re now well past when any such breaking changes would be considered. but has anyone ever attempted to reimplement the clojure.core functions with protocols as “clojure 2.0” library?

Alex Miller (Clojure team)15:11:15

not to my knowledge. it would dramatically affect the java/clojure split and how collections were implemented I think. certainly clojurescript is the best reimagining by the person with the most context :)

Noah Bogart15:11:46

yeah, it makes sense from a pragmatic standpoint, as interfacing with java is a big reason to use clojure, but it’s a pain point when working strictly within clojure that the existing architecture isn’t enough to do this stuff. i’ve never actually looked at clojurescript’s core library or how it’s implemented. maybe i’ll take a wack at it myself to see how things break!

Alex Miller (Clojure team)17:11:33

if you do, I have been told that looking at the very early commits of clojurescript (not where it is now) is probably the best entry point

👍 1

Fair enough. Is gen-class the way to go here, or is there some other, simpler way of doing it?

Alex Miller (Clojure team)14:11:19

I guess you have to extend something to make it an exception, so either gen-class or proxy


Alright, thanks 🙂


In a ring app, how do i access the body of a text/plain POST ? My repl just hangs when i attempt to slurp the body. The body shows #object[org.eclipse.jetty.server.HttpInputOverHTTP 0x4f4b65da "[email protected][c=0,q=0,[0]=null params shows {}


are you def’ing the response and trying to slurp after the request is handled?


the syntax in alt! has me confused. i'm trying to exit a go-loopthrough a signalling "exit channel". would this be the right approach?


(alt! (blocking-operation ...) (recur)
  exit-ch nil)


also, does alt! park the calling thread? (blocking-operation ...)here runs inside it's own thread .


(the above code works, I'm just not sure I'm getting what I want in terms of not blocking the calling thread with blocking-operation)

Alex Miller (Clojure team)18:11:18

if blocking-operation is truly blocking, then you shouldn't do this in a go-loop at all


well, it's actually a long polling HTTP call, occasionally returning data to be processed. when no data is available, it blocks.

Alex Miller (Clojure team)18:11:15

well if you do that the right number of times, you will block your entire app


if blocking-operation launches a thread (which returns a channel) that's fine

Alex Miller (Clojure team)18:11:46

yes, that would be fine


yes, blocking-operation launches a (thread ...)


you're alting over that channel's result, or the exit channel, whichever returns first


cool. and does alt!park or am I eating up one of the go threads as well?