Fair points. Well, leaving the possibility to document the code from just anywhere is what I had in mind.
Le samedi 26 avril 2014 22:52:41 UTC+2, Jason Felice a écrit : > > Personally, I like documentation in the same place as the code it > documents.... And I'd love to have the tests in the same file as well. > > In both cases, I think the things are highly coupled by their nature, and > therefore I want them together (OK, tests aren't always - in the cases they > aren't, put them in a separate file). I've reminded people that the SRP > ("any piece of code should have one reason to change") implies the > converse, which I phrase as "Code which changes together, stays together." > > That said, I like the idea of more structured documentation. (Possibly > including test cases! Python has test runners which verify examples in doc > strings, for example.) > On Apr 26, 2014 4:31 PM, "Gary Trakhman" <gary.t...@gmail.com<javascript:>> > wrote: > >> 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.v...@gmail.com<javascript:>> >> 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 >>> :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 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. >>> >> -- >> 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. >> > -- 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.