Hi Valentin, Thanks for starting such an excellent discussion, and your initial posting is very well put. I think you should talk to Chris Zheng who has developed a tool called lein-midje-doc [1] which it seems answers much of your questions. I've been using it for months now and it is the centrepiece of my development workflow.
lein-midje-doc combines the Midje test framework with a literate programming model. Essentially you write documentation (as you describe) in Clojure, with your text in Markdown, structured using Clojure data structures, and sample code which shows the reader how to use the code. The sample code can be either just that (ie it produces a code block but is merely pretty-ptinted text) by putting the sample code in a (comment ...) form, or else executable doumentation/test code of the form: (+ 1 2 3) => 6 by putting the sample code in a Midje (fact ...) form. Here's an example doc [2] I produced recently which compares two encoders for my Clortex project. As you can see, it's a mini-paper which goes through the shortcomings of an existing encoder, then argues for, explains and demonstrates a new design. The doc has an include directive which pulls in the source code for the new encoder in the middle. In addition to this, docstrings are still hugely useful and should form part of the workflow for accessing quick summary and usage information on functions. I use Marginalia [3] to convert docstrings into a side-by-side doc-and-code presentation. Finally, I'm using the wonderful hoplon-reveal-js [4] to produce beautiful presentations about the work and the software. It's all done in ClojureScript and is a huge step in the direction you're talking about. I would also point you to Gorilla REPL [5] and Session [6] for another take on doing literate programming and mixing markup with code in Clojure. Hopefully there's some way these guys can combine their projects, the combination would be scary! Regards Fergal [1] https://github.com/zcaudate/lein-midje-doc [2] http://fergalbyrne.github.io/rdse.html [3] https://github.com/gdeer81/marginalia [4] https://github.com/oubiwann/hoplon-reveal-js [5] https://github.com/JonyEpsilon/gorilla-repl [6] https://github.com/kovasb/session On Sun, Apr 27, 2014 at 5:21 AM, Mars0i <marsh...@logical.net> wrote: > Some thoughts: > > Having concise documentation in the same place as the code minimizes a > certain kind of work: I want my functions to be commented in the source > file so that someone reading it later (maybe me) will quickly understand > what they're supposed to do. If Clojure didn't have docstrings, I'd put > similar information, although maybe more terse, in comments. As it is, I > just write the docstring, and I've accomplished two things in one. If all > of the documentation was in another file, I'd have to do at least 1.5 times > more work just to produce the kind of docstrings I produce now. > > Some docstrings (e.g. for xy-plot in Incanter) are too long for convenient > use at a repl. So I appreciate the idea of providing different levels of > documentation. What's displayed by default at a prompt should be short. > > I like the general idea of the Valentin's proposal, but I don't understand > every bit of it. It sounds complicated. Personally, I'd rather see > something that's relatively simple, and good enough, than something that's > perfect but unwieldy. If it's too difficult, people won't use it, or > they'll waste time, or feel that the Clojure community expects them to > spend too much time on something that detracts from what's important. I am > someone who I think has put more time into documentation more than most of > the programmers I've worked with. I'm in favor of encouraging more > documentation of code. But documentation tools should not make the process > much harder than it is. Ideally, they should make it easier, but some > extra cost is worthwhile for extra payoff later. > > -- > You received this message because you are subscribed to the Google > Groups "Clojure" group. > To post to this group, send email to clojure@googlegroups.com > Note that posts from new members are moderated - please be patient with > your first post. > To unsubscribe from this group, send email to > clojure+unsubscr...@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en > --- > You received this message because you are subscribed to the Google Groups > "Clojure" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to clojure+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/d/optout. > -- Fergal Byrne, Brenter IT Author, Real Machine Intelligence with Clortex and NuPIC https://leanpub.com/realsmartmachines Speaking on Clortex and HTM/CLA at euroClojure Krakow, June 2014: http://euroclojure.com/2014/ <http://www.examsupport.ie>http://inbits.com - Better Living through Thoughtful Technology http://ie.linkedin.com/in/fergbyrne/ https://github.com/fergalbyrne e:fergalbyrnedub...@gmail.com t:+353 83 4214179 Formerly of Adnet edi...@adnet.ie http://www.adnet.ie -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
