Compojure 0.4.0 has (finally) been released.

It's more or less the same as 0.4.0-RC3, but I updated the Ring
dependency to 0.2.3, and I sneakily added response type handling for
ISeq and InputStream.

Is there work underway to provide more complete documentation for
Compojure?  I may soon have some time to help in that area, if you're
interested.

To that end, I've been considering setting up a site for Clojure web
development, which would start by covering the basic ideas of Ring,
and then discuss how to use Ring in conjunction with libraries like
Compojure or Moustache, how to generate HTML with Hiccup or Enlive,
and so forth. I was thinking something similar in style to the Git
Community Book [http://book.git-scm.com/].

Does this sound like a good idea to you?

On Jun 24, 2010, at 8:01 AM, James Reeves wrote:

In http://wiki.github.com/weavejester/compojure/route-syntax, it says
to refer to Clojure's own destructuring docs, but Compojure's syntax
doesn't look much at all like Clojure's syntax.  It might be nice to
show the equivalence explicitly:

(let [{:foo foo} request] ...)
=> (GET "/" [] {:foo foo} ...)

Even this won't make sense unless you know exactly how Ring works,
that your routes are dealing with a Ring request map that always has
certain standard keys.  A note saying "Go read the Ring SPEC document
to see what keys are available, and keep in mind that more keys may be
added by middleware" would be helpful here.

The docs say:

A lot of examples are given like this:

(PUT "/user/:id" [id & updated-attrs]
  (update-user id updated-attrs))

OK, so what does that do exactly?  What is the value of updated-attrs
now?  It'd be nice to spell it out explicitly.  Or if I want to figure
out what it does myself, how do I inspect it?  How do you debug a
Compojure app?  I still don't really know if I'm doing it the best way
sometimes, to be honest.  I println from my handlers, or have a route
return {:body (pr-str request)}, or I throw an exception with an
object I want to inspect and use stacktrace-dumping-to-HTML middleware
to look at it.

The examples for Ring and Compojure both are always at a "hello world"
level, which is OK, but I've seen a lot of people ask for more
complex / real-world examples.  Examples of integrating with Hiccup or
Enlive would be excellent, as you mention, because a user is almost
certainly going to need one of those (or equivalent).

And then there's the "Now how do I deploy it?" issue, which would
benefit greatly from documentation.

If not for this group and for reading the source for most of Compojure
and Ring, personally I would still be in the dark about how a lot of
things work.  I guess I prefer my documentation dumbed down a few
notches.  A book-style document would be a great way to solve most or
all of this, so I think it's a great idea.  Distributing the doc-
writing work to the community is also a good idea.