Phil Hagelberg <p...@hagelb.org> writes: > On Saturday, April 26, 2014 9:21:26 PM UTC-7, Mars0i wrote: >> I like the general idea of the Valentin's proposal, but I don't >> understand every bit of it. It sounds complicated. Personally, I'd >> rather see something that's relatively simple, and good enough, than >> something that's perfect but unwieldy. If it's too difficult, people >> won't use it, or they'll waste time, or feel that the Clojure >> community expects them to spend too much time on something that >> detracts from what's important. > > Double-inc[1] on this. Clojure needs people who care about documentation > far more than it needs another documentation system. Don't try to apply a > technical solution to a social problem.
Consider this argument, of the same form. What the JVM needs is people who care about writing good code far more than it needs another JVM hosted language. Don't try and apply a technical solution to a social problem. Following this logic, we can just dump Clojure and use Java; in fact, if we do this, we will achieve a better documentation system than we have at the moment, because javadoc is better than Clojure's system. Of course, technical solutions don't solve all problems, and authoring documentation is difficult to start off with; but Clojure's current system -- an unstructured string -- is not a good tool. Compare Emacs doc Compare these two strings: Returns a new seq where x is the first element and seq is the rest. Create a new cons, give it CAR and CDR as components, and return it. In the latter, we can distinguish CAR and CDR as parameters. In the former, cannot. We could look at arglist :arglists '([x seq]) which tells us. However, we have "a new seq" and "seq is the rest" -- one refering to the formal parameter and the other refering to the clojure abstraction. And neither refering to clojure.core/seq which we might otherwise want to hyperlink to. We could change it to this.... Returns a new object implementing the ISeq interface, where the formal parameter x is the first element and the formal parameter seq is the rest. which avoids the ambiguity, but this is long winded. We need some structure, or at least conventions in Clojure documentation. The lack of this is the technical problem. That we have many potential technical solutions is social problem, not that we have any. Phil -- 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.
