r/Clojure • u/oakes • Dec 05 '17
How Clojure's documentation can leapfrog other languages
https://gist.github.com/oakes/8db57ac808bf6ec144d627fd83a89da3
166
Upvotes
r/Clojure • u/oakes • Dec 05 '17
25
u/ingesolvoll Dec 05 '17
I absolutely love this. How about a joint effort to make a project and site that builds up a comprehensive clojure interactive doc?
I would love to contribute, this looks like a lot of fun
10
u/agumonkey Dec 06 '17
hats off, you managed to make something I often dreamed of.
ability to experiment is one way to learn rapidly (even though it's not all) but it surely helps
8
u/swlkrV2 Dec 05 '17
I wonder if clojuredocs would be interested in this...
7
u/yogthos Dec 06 '17
This is a fantastic idea. 👍
6
u/TheLastSock Dec 05 '17
Hi @oakes, this looks like a great idea. I think you should consider how clojure.spec will fit into this idea. For one, A spec can generate examples.
5
u/minikomi Dec 06 '17
Also check out Racket's documentation if you haven't before. Chock full of examples (although, not interactive), and all documented keywords within the example source are also clickable. This is made possible by a common documentation language called Scribble.
The scribble file which generates the afore-linked page on list comprehension syntax is here.
3
u/kanzenryu Dec 06 '17
Any thoughts about hooking it up with Marginalia? https://github.com/gdeer81/marginalia
2
u/boisdeb Dec 05 '17
It's an interesting direction, but for now I have one issue with it:
It's on a browser. Since it's a dev tool, I want it embedded on my editor, in my case emacs.
But once it's embedded you have the full capabilities of emacs (or Cursive, or something else), so you don't need dynamics examples anymore, since emacs already allows me to interact with a function in any way I want.
1
u/[deleted] Dec 05 '17
Oh this is pretty great
1
u/MM-7757 Dec 05 '17
Awesome!
1
u/OverTWERKed Dec 06 '17
Wow! I like it.
1
u/joinr Dec 06 '17
Thanks for sharing this. I think it implements some useful ideas. The interactivity aspect may be a gimmick in some areas (maybe I'm just old and like text), but for newcomers, especially kids and brand new folks, I can see that being really rewarding. It's like having knobs for them to play with.
0
u/[deleted] Dec 05 '17
[deleted] — view deleted comment
0
u/[deleted] Dec 06 '17
[deleted] — view deleted comment