Sean Corfield <s...@corfield.org> writes: > Short, clear docstrings and well-structured code with well-named > symbols short provide enough information for maintenance.
But, sadly, not enough documentation for use. The state of Clojure survey brings up complaints about the documentation of clojure.core every year. Partly this because the documentation is not very good -- I still use Clojuredocs regularly, even though it's rather rusting away being on 1.3. I rarely read the documentation, just skip to the examples. But, partly, it's because the documentation format is just too simple. Javadoc, for example, is far better. And is Javadoc literate programming? If it is, then the idea that "no one uses literate programming" is wrong, if it is not, then literate programming is irrelevant. Even some simple documentation standards for Clojure, distinguishing parameters, functions and so on would be a step forward. And it needs to go into clojure.core so that tools support it. Phil -- 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.
