I added some stuff on the Elisp documentation. Others can update if they think I am wrong!
Phil Val Waeselynck <val.vval...@gmail.com> writes: > So it would be nice if people who are knowledgeable about other doc systems > could contribute to it. From what I see, that may involve Tim for Emacs, > Sean for reStructured, and Daniel for docco, for example? > > Thanks in advance! > > Le 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. >> >> >> -- 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.
