This is a lovely idea. I think prismatic schema is one well-accepted way to document data shapes, but it's expected to be used inline. It would be nice to have flexibility in what description systems are used in addition to flexibility of where the docs live.
I agree that being able to see and reason about bare code with no hassle is a (personal) demotivator for documentation, but where the docs live should be up to the implementor. Having a code-based system means we can use and improve existing runtime tooling to navigate and interact with it. This would make a great cider middleware :-). On Saturday, April 26, 2014, Val Waeselynck <val.vval...@gmail.com> 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<javascript:_e(%7B%7D,'cvml','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<javascript:_e(%7B%7D,'cvml','clojure%2bunsubscr...@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<javascript:_e(%7B%7D,'cvml','clojure%2bunsubscr...@googlegroups.com');> > . > For more options, visit https://groups.google.com/d/optout. > -- 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.
