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.
