Clojurians Log v2

A quick cut at parsing doctests in @pithyless’s style - https://github.com/arrdem/stacks/pull/4. It’s definitely workable.

Good point @noisesmith - I was aware of the ^:test metadata, but I did not want to clobber possibly existing tests attached to the var. (I always wondered why deftest works the way it does, why it’s not idiomatic to just see ^:test attached to the function itself. Or have you seen that in practice?) You’re right about making things simpler, it was a very rough cut just to be able to play with the “ergonomics” of the doctest approach.

Very cool @arrdem! That was an unexpected and quick turnaround for a random comment posted to Slack 🙂

I’ve found the doctest approach satisfying to encourage me to write documentation for public api functions, but I have not used it in anger on a project yet, because I was not sure if the >>, =>, and :> distinction was even a good idea. Was hoping for some feedback from others.

Here’s an example borrowed from weavejester/medley, where I was trying to justify to myself that doctest trumps tests in another part of the app as a communication tool:

(defn abs
  "Return the absolute value of number `x`.

  Works with all numbers supported by the runtime
  and correctly handles integer overflow, unike `Math/abs`.

      >> (abs -3)
      => 3

      >> (abs -3/5)
      => 3/5

      >> (abs -3.5)
      => 3.5

      >> (abs Integer/MIN_VALUE)
      => 2147483648
  "
  {:attribution "weavejester/medley"
   :added "0.1"}
  [x]
  (if (neg? x) (- x) x))

@pithyless it's a neat little idea, and I already had 90% of the tools to hand 😛

My line of thinking was can I get away with using doctest for communication and edge-cases, and test.check for completeness. ¯\(ツ)/¯ Not sure, but open to feedback.

Yeah I totally buy that.

@arrdem - you’re right, it does look a lot more sane and robust in your approach. 😄 I’m taking a week off for the holidays, but I’ll happily pick this up the week after next in anger 🙂

Enjoy then! This fills a need for me at $DAYJOB so I'm throwing time at it somewhat actively. Would definitely be glad for the help when you're back tho, especially if you're a better hand with web/ring anything than I am.

I wonder if @bozhidar would not be interested in joining this channel and adding his thoughts. His talk on the problems with the current clojure docs ecosystem was one of my inspirations to take a stab at this.

Yeah. Part of my experience from Grimoire is that even though I built a dead-easy-for-me system for writing docs, its bar was still too high for most people to figure out how to contribute let alone contribute meaningfully. The goal of Stacks is essentially to ... just build a tool you can slap more frontends / DSLs ontop of so you can meet devs where they are and drive the activation energy price down.

Anyway. Bedtime here.

Well, it seems there’s a problem of soliciting contributions across the board in the Clojure community. Forget about docs - most of the major Clojure projects have almost contributors outsider their primary maintainer(s). That’s a stark contrast with what I’m used in the Ruby community (for instance).

I’d normally expect people to contribute to things like REPLy, compliment, cljs-tooling, nREPL, etc like crazy…

And way more doc contributions, of course…

Yeah. I don't really get it either, but I think part of the problem is that largely hostile core has discouraged the formation of a traditional community. Clojurians are more of a loosely affiliated user group than members of a community.

There also seems to be a lot of code that's written by someone on contract, ossd and kinda left rather than meaningfully maintained or committed to community ownership.

@arrdem “largely hostile” is both wrong and deeply insulting. I’m at a loss as to what you think the 12k+ people here are if not a community.

@alexmiller It has been the experience of many folks (myself included) that contributing to core is difficult. I understand why this is, meant no offense, and difficult or defensive would have been a better choice of words than hostile. My intent was to point out that this leads to the emergence of a different kind of broader community dynamics, not to cast aspersions at the warm and friendly people I’ve met here. I like your work enough that I’ve stuck around this long 😄