Any Result? Talk is cheap On Sunday, April 27, 2014 12:39:04 AM UTC+8, Val Waeselynck wrote: > > 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.
