Le samedi 10 mai 2014 16:09:11 UTC+2, tbc++ a écrit : > > 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? >
Actually, I was thinking of making something that is completely external to the metadata map, so as to make it nonintrusive. A bit like a test library. > > Timothy > > > On Sat, May 10, 2014 at 7:44 AM, Val Waeselynck > <val.v...@gmail.com<javascript:> > > 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 :curriedfor 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 clo...@googlegroups.com<javascript:> >> Note that posts from new members are moderated - please be patient with >> your first post. >> To unsubscribe from this group, send email to >> clojure+u...@googlegroups.com <javascript:> >> 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+u...@googlegroups.com <javascript:>. >> 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.
