http://dev.clojure.org/jira This file is an XML representation of an issue en-us 4.4 649 25-07-2011 http://dev.clojure.org/jira/browse/CLJ-835 Clojure <p>The :hierarchy option for defmulti should be passed a var, but this is not mentioned in the doc string.</p> <p>The error message from passing the hierarchy directly is rather cryptic:</p> <p>Evaluation aborted on java.lang.ClassCastException: clojure.lang.PersistentArrayMap cannot be cast to clojure.lang.IRef (SOURCE_FORM_44:19).</p> 1.2, 1.3 beta3 CLJ-835

defmulti doc string doesn't mention needing to be passed a var for the value of :hierarchy

Defect Minor Open Unresolved Unassigned Hugo Duncan Fri, 2 Sep 2011 15:09:00 -0500 Wed, 19 Dec 2012 07:59:17 -0600 Release 1.2 1 2 <p>Modified doctoring to clarify the usage of <tt>:hierarchy</tt>.</p> <p>New patch: '0001-<a href="http://dev.clojure.org/jira/browse/CLJ-835" title="defmulti doc string doesn&#39;t mention needing to be passed a var for the value of :hierarchy">CLJ-835</a>-Refine-doc-string-for-defmulti-hierarchy-opt.patch' 10/May/12.</p> <p>I've attached a new doc string patch in response to Andy Fingerhut's request posted here: <a href="https://groups.google.com/forum/?fromgroups#!topic/clojure-dev/i7H82fJYL-U">https://groups.google.com/forum/?fromgroups#!topic/clojure-dev/i7H82fJYL-U</a></p> <p>Andy's request stated "Attached patch seems to have spelling mistakes, and perhaps could be worded more clearly."</p> <p>I hope my new patch is an improvement upon what was there.</p> <p>This patch supersedes '0001-Clarify-docstring-for-defmulti.patch' from 14/Sep/11.</p> <p>This is a million times better than what was there before, but (who knew!?) it could be better. A couple points of contention:</p> <ul> <li>The order under the <tt>:hierarchy</tt> section seems off. I would start with an overview of what a hierarchy is including a definition of the global hierarchy map (it's mentioned, but glossed over). I'd then move on to an example impl. Finally, I'd then add the discussion starting "Multimethods expect..." immediately followed by an example.</li> </ul> <ul> <li>In the <tt>isa?</tt> example it would be great to show the return value.</li> </ul> <ul> <li>You mention that the hierarchy should be supplied as a reference, which is correct, however you talk about #'. The link between e.g. var and #' could be a bit more explicit. Maybe the sentence about #' could be parenthetical?</li> </ul> <ul> <li>It's ok to finish with a very small example of its use in <tt>defmethod</tt>, in fact a simple example specifying methods for <tt>::shape</tt> and <tt>::circle</tt> would clarify the intent nicely.</li> </ul> <p>Please leave examples out of docs strings. Use precise language.</p> Approval Incomplete Global Rank Patch Code