I struggled with Clojure's documentation system while writing https://github.com/phillord/tawny-owl. The problem here is that I am using an underlying Java library; in the ideal world, I would like documentation on vars to come from the Object held in the var. But there is no way to achieve this in Clojure because it's a :doc string in the metadata.
Now, with tawny-owl, the documentation is still not very good; I would like to improve it, but many parts of the documentation are not specific to Clojure, but need to relate to the problem domain for the libary. And I would like to be able to publish that part of the documentation independently from Clojure -- so being able to transclude external files would be very useful indeed. Even on a simple level, I get frustrated that, in clojure, there is no typographical way to distinguish a parameter, a function and a normal word. One simple way to allow this would be to let :doc take a one-arg closure (taking the var). Phil Val Waeselynck <val.vval...@gmail.com> writes: > 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. -- Phillip Lord, Phone: +44 (0) 191 222 7827 Lecturer in Bioinformatics, Email: phillip.l...@newcastle.ac.uk School of Computing Science, http://homepages.cs.ncl.ac.uk/phillip.lord Room 914 Claremont Tower, skype: russet_apples Newcastle University, twitter: phillord NE1 7RU -- 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.
