[emidln]

The author seems to have missed the Ring Spec [1]. It provides a complete breakdown of what is in a ring response and a ring request for the core spec.

The middleware (at least those that ship with ring) are all documented in docstrings explaining the keys they add or work on. This is available in the repl via `clojure.repl/doc` or inspective `(:doc (meta foo))`. It's available in your editor if your editor has clojure support (I only use vim and emacs, and both of these can search/display docs on clojure code). There is also nicely formatted api docs at [2].

[1] - https://github.com/ring-clojure/ring/blob/master/SPEC [2] - http://ring-clojure.github.io/ring/index.html

That said, it would be nice if more of clojure was documented using an executable schema or type system, ala Schema or core.typed. The author would have done well to pick less well-documented libraries though.

[elbenshira]

Yes, I did miss the ring spec. But as a beginner to ring, I'm not sure how I was suppose to know that such a document exist.

For the most part, Ring is well-documented. But, as you noted, human-typed doc strings go only so far. I applaud the writers of ring in their discipline, but certainly we can do better than depending on human discipline.

You even noted, I picked "less well-documented libraries." I didn't pick them because they were not well-documented—I picked them because I'm using them!

[emidln]

I suspect you might have encountered the SPEC if you opened the README of the ring project or visited its github page (which displays the README by default). It's mentioned and linked in that README:

From https://github.com/ring-clojure/ring:

    Ring is a Clojure web applications library inspired by Python's WSGI and Ruby's Rack. By abstracting the details of HTTP into a simple, unified API, Ring allows web applications to be constructed of modular components that can be shared among a variety of applications, web servers, and web frameworks.
    The SPEC file at the root of this distribution provides a complete description of the Ring interface.