Docs: Mention that manual setup code may be nested in facts

[holyjak]

The current documentation doesn't make it clear that this is legal:

(facts
  (let [test-users (make-users-with-ids 1 2 3)]
    (setup test-users) ;; Wow, I can call a setup method before a group of facts!

    (fact "about users" (get-user-by-id 1) => truthy)
    (fact "another fact on the same data" (get-user-by-id -99) => nil)
    ...)

Contrary to the standard setup/teardown solution of with-state-change, this makes it possible to run the setup only once for a group of facts, which is desirable if the setup is expensive. (And I guess we could get teardown by wrapping the facts in try-catch and running the teardown code in finally)). It would be nice to describe this on the https://github.com/marick/Midje/wiki/Setup-and-teardown page. If this is not a recommended practice, what would be the optimal solution?

[marick]

One of the core ideas of Midje is that its expressions (facts, =>, whatever) are really just ordinary Clojure code, run in sequence with whatever code surrounds them. From that point of view, it's unsurprising that setup runs as expected. What's surprising is that there's a "magic" mechanism that runs code invisibly before or around facts.

There are two things that need to be fixed:

1. The documentation should be clarified. I don't think the above "core idea" is actually mentioned.
2. The mechanism for designating code or prerequisites to apply to some / all / some subset of facts isn't right. I don't know what's right, though. I hope, in my vast leisure time, to analyze my increasingly large set of real-job tests to figure out what would work better.