If you plan on having this documentation apply to clojure.core.* you'll probably want to pull in Alex Miller or start a conversation in clojure-dev. I'd hate to see a bunch of decisions made, just to find out that Rich has a completely different view, a view that might have been nice to know before plans were finalized.
Or perhaps a metadata modification system can be created? One that allows people to import clojure libs that adds new doc data to existing vars? Timothy On Sat, May 10, 2014 at 7:44 AM, Val Waeselynck <val.vval...@gmail.com>wrote: > Here > :<https://docs.google.com/spreadsheets/d/1HyS9qstgEqmdv0MtDm3xEsImnDjCYQhar1PQP3fzwMc/edit?usp=sharing>I > think it would help if we had a panoramic view of the existing > documentation systems and what we could borrow from them. I could only > think of a Google Drive spreadsheet for this, but if anyone has a better > idea... :) > > 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 >> :prerequisiterelationship 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. > -- “One of the main causes of the fall of the Roman Empire was that–lacking zero–they had no way to indicate successful termination of their C programs.” (Robert Firth) -- 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.
