Hello to all, *Short version :* I think Clojure needs a documentation system in Clojure, I would like to know if some efforts exist in that direction, and I am willing to create it / contribute to it.
*Long version :* I've been thinking for a while that the Clojure community could benefit a lot from a more sophisticated and ergonomic documentation system. I have seen some existing plugins like lein-sphinx, but I think it would be really good to have documentation that would be written in Clojure, for the following reasons : - we're all very fond of Clojure data structures and their syntax. (I don't know about you, but I find that even HTML looks better in Clojure<https://github.com/weavejester/hiccup>than in HTML). Plus, Clojure programmers already know how to edit them. - (better reason) The facts that Vars are first-class citizens and that symbols can be referred explicitly with hardly any ceremony (macros) are a exceptional opportunity to make smart and highly-structured documentation very easily. - if it's in Clojure, Clojure programmers can seamlessly build *ad hoc*documentation functionality on top of it to suit their own particular needs. I haven't found anything of the like yet, and if it exists, I would be grateful if someone would redirect me to it. Here are *my thoughts on this :* 1. Clojure doc-strings, although they are quite handy as reminders and for doc-indexation, are *too raw a content*. Even when they are done right, they tend to be cumbersome, and it's too bad to have such concise code drown in the middle of so much documentation. What's more, I believe that when programmers program a function (or anything), they tend to think more about the implementation than the (uninformed) usage, so they have little incentive to make it right. 2. Building on 1. having a system where documentation and programs live in separate files, in the same way as tests, would enforce a healthy separation of concerns. Importantly, it would make life much easier on the Version Control perspective. 3. Documentation should probably be made differently than what people have got accustomed to by classical languages. Because you seldom find types, and because IMHO Clojure programs are formed more by factoring out recurring mechanisms in code than from implementing intellectual abstractions, the relevant concepts tend not to be obvious in the code. Since in Clojure we program with verbs, not nouns<http://steve-yegge.blogspot.fr/2006/03/execution-in-kingdom-of-nouns.html>, I think *documentation is best made by example*. 4. Documentation of a Var should not be a formal description of what it is and what it does with some cryptically-named variables. *Every bit of documentation should be a micro-tutorial*. Emphasis should be put on usage, examples, tips, pitfalls, howtos. 5. There should be structure in the documentation, and it shouldn't be just :see-also links - *there should be semantics* in it. For example, some functions/macros are really meant to be nothing but shorthands for calling other functions : that kind of relationship should be explicitly documented. 6. Documentation should not be just information about each separate Var in a namespace. There should be a hierarchy to make the most useful elements of an API more obvious. Also, adding cross-vars documentation elements such as tags and topics could make it easier to navigate and understand. 7. *Documentation in the REPL is great*, it was one of the very good surprises when I started learning Clojure. However, a rich and good-looking presentation like in Javadocs would be welcome too. Of course, all of the above are just vague principles. Here is *some functionality I suggest for a start :* 1. Documentation content elements could be written in a Clojure DSL emulating some kind of docbook-like markup language. 2. On the user side, the documentation would be accessible through a generated web interface, a REPL interface, and maybe other formats like Wiki. 3. Documentation could be programmed anywhere in a project by simply referring to the relevant Vars and calling the documentation API. Ideally, there would be a dedicated folder for documentation files, and a Leiningen plugin to compile them and generate the HTML from them. 4. I often find myself lost because I have no idea what shape some arguments to a function should have, such as config maps and maps representing application-specific models. To adress this, I propose to explicitly declare and describe *"stereotypes"* in the documentation. Such stereotypes could be, for instance, "JDBC connection" or "Ring middleware". From what I have seen, some good work<https://github.com/prismatic/schema>has already been done in that direction, but it would be good to make room for it in documentation. 5. Weigh the documentation contents by importance, to allow for displaying the documentation with several levels of details. 6. Cross-vars, semantic documentation with *topics*, *tags*, and *links*. *Topics* would group several API elements together to explain a technique or concept; they could have a :prerequisite relationship to help the reader navigate them. I imagine *tags* giving hints on various aspects of a Var, such as :curried for a function, or :utility, or :use-with-caution, etc. *Links* could be such things as the famous :see-also, but could also represent more precise relationships, such as :calls-to, :often-used-with, :similar-to, etc. 7. In addition to small, Var-specific, self-contained code samples, there could be larger examples (e.g sample applications), and pointers from the documentation to specific points in these examples. 8. There could be other types of documentation than just static description, such as exercises, koans, quizzes, etc. I would like to know what work has already been done in that direction, and if you agree that this is useful, I am willing to help design and implement it. Your reactions are very welcome. Bests, Valentin Waeselynck. -- 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.
