Sean Corfield <s...@corfield.org> writes: > On May 6, 2014, at 8:11 AM, Phillip Lord <phillip.l...@newcastle.ac.uk> wrote: >> I've used this example before; consider this unstructured string from >> `cons`. >> >> Returns a new seq where x is the first element and seq is >> the rest. > > Just because one (or several) of the clojure.core function docstrings are > poorly written, doesn't mean Clojure's current documentation system is broken. > This simply comes back to developers needing to write _better_ documentation, > not _more_ documentation.
Indeed, and the need for some standards comes from this. Let's rewrite the cons docstring so my (perverse) interpretation cannot hold. Returns a new seq where the value of the parameter x is the first element and the value of the parameter seq is the rest. Now, this is more correct, but hard to read. This is why we need (at least) some standard markup in doc strings. The Emacs style Returns a new seq where X is the first element and SEQ is the rest. Better, I think would be: Returns a new seq where X is the first element and SEQ is the rest. See also: seq, seq?, first, rest And then add Returns a new seq where X is the first element and SEQ is the rest. See also: `seq', `seq?', `first', `rest' http://clojure.org/sequences These are small changes, no revolutionary ones. Literate programming or otherwise is an interesting discussion, but at least getting up to the level of Emacs (a 20 year old lisp!) would be good. If you think I am wrong, then show me *any* book on programming that uses no typography to distinguish semantically different parts of the document. > Adding complexity and weaving heapings of prose in amongst the code isn't > going to make the developer that wrote the above rewrite it in a better way. > You'll just end up with more bad documentation getting in the way of what the > code actually does. Bad documentation is worse than no documentation. At least > with no documentation, the code doesn't lie. The "use the source, Luke" argument is a good one in some cases. In this case, though, this is the source. (def ^{:arglists '([x seq]) :doc "Returns a new seq where x is the first element and seq is the rest." :added "1.0" :static true} cons (fn* ^:static cons [x seq] (. clojure.lang.RT (cons x seq)))) So, not that helpful. You can, of course, look up RT.java if you know the "." notation (which you might not, because it's not meant for normal use). which brings you to this... static public ISeq cons(Object x, Object coll){ //ISeq y = seq(coll); if(coll == null) return new PersistentList(x); else if(coll instanceof ISeq) return new Cons(x, (ISeq) coll); else return new Cons(x, seq(coll)); } which is not documented at all and which is defined to be an implementation detail. So, no the code doesn't lie, but it doesn't necessarily tell you much either. 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.
