Sorry I have been late to react to all this, since I'm the one who started it all.
First, *as a side note* : I have nothing against docstrings. I acknowledge their benefits, I think we should keep using them and I enjoy them every day like all of you. My point was just that they were not enough for all documentation, I probably wasn't very clear on that. Stop shooting :) @Fergal : thanks for such a great tour. It seems I have a lot of catching up to do before I have a keen understanding of the currently existing options. Nevertheless, I'll try to make a relevant contribution to the discussion. Given some of the answers, I'd like as a precaution emphasize the fact that I'm not trying to "sell" you a documentation system nor impose a dogma. My intent in proposing these approximative features was that, through some refining, some proposing and some discarding, the discussion will converge to a precise idea of what we want for documentation and how we should do it. As for what Gregg and Sean objected - that Clojure code is self-sufficient as documenting itself - I have to simply disagree. I do not want to have a theoretical discussion on this, because I think it's pointless; it is an empirical observation to me that foreign Clojure code tends to be difficult to understand. I have felt that pain, many times and despite all my stubbornness, which is why I finally posted here. I I'm the only one, please tell me. I think it is very important to raise the awareness of all Clojure programmers, especially library authors, that there is a significant asymmetry of information here : namely, it's easier than ever to go from intent to code, and much harder to go the way back. I see it at work when I edit my own code too : the programs seem to organize themselves naturally as I write them, sometimes in such a mechanical way that I have difficulties finding names for the abstractions I program, and I do get a crystal-clear understanding of them; but I'm quite sure that it would be very obscure to me if I had not witnessed the process. Try to make a Ring middleware or a monad self-explanatory with just code and a schema. Undoubtedly, library authors will feel this duty of documentation like a hinderance. I believe this is a necessary tradeoff to make. Besides, if you're code changes so fast that documentation quickly becomes obsolete, isn't that a sign that your API isn't ready to be exported? Anyway, I think speculating about the necessity of such a documentation system is not the best thing to do - I suggest we give it a try, and then everyone can decide for themselves if it's useful. After all, it's in Clojure, so this should not take too long, right ? ;) samedi 26 avril 2014 18:39:04 UTC+2, Val Waeselynck a écrit : > > 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.
