Clojure

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

Details

  • Type: Defect Defect
  • Status: Closed Closed
  • Priority: Minor Minor
  • Resolution: Completed
  • Affects Version/s: Release 1.2
  • Fix Version/s: Release 1.6
  • Component/s: None
  • Labels:
  • Environment:
    1.2, 1.3 beta3
  • Patch:
    Code
  • Approval:
    Ok

Description

The :hierarchy option for defmulti should be passed a var, but this is not mentioned in the doc string.

The error message from passing the hierarchy directly is rather cryptic:

Evaluation aborted on java.lang.ClassCastException: clojure.lang.PersistentArrayMap cannot be cast to clojure.lang.IRef (SOURCE_FORM_44:19).

After:

user=> (doc defmulti)
-------------------------
clojure.core/defmulti
([name docstring? attr-map? dispatch-fn & options])
Macro
  Creates a new multimethod with the associated dispatch function.
  The docstring and attribute-map are optional.

  Options are key-value pairs and may be one of:

  :default

  The default dispatch value, defaults to :default

  :hierarchy

  The value used for hierarchical dispatch (e.g. ::square is-a ::shape)

  Hierarchies are type-like relationships that do not depend upon type
  inheritance. By default Clojure's multimethods dispatch off of a
  global hierarchy map.  However, a hierarchy relationship can be
  created with the derive function used to augment the root ancestor
  created with make-hierarchy.

  Multimethods expect the value of the hierarchy option to be supplied as
  a reference type e.g. a var (i.e. via the Var-quote dispatch macro #'
  or the var special form).

Patch: 0001-CLJ-835-ReRefine-doc-string-for-defmulti-removing-examples-and-solidifying-language.patch

Screened by: Alex Miller

Activity

Hide
Meikel Brandmeyer added a comment -

Modified doctoring to clarify the usage of :hierarchy.

Show
Meikel Brandmeyer added a comment - Modified doctoring to clarify the usage of :hierarchy.
Meikel Brandmeyer made changes -
Field Original Value New Value
Attachment 0001-Clarify-docstring-for-defmulti.patch [ 10361 ]
Hide
Scott Lowe added a comment -

New patch: '0001-CLJ-835-Refine-doc-string-for-defmulti-hierarchy-opt.patch' 10/May/12.

I've attached a new doc string patch in response to Andy Fingerhut's request posted here: https://groups.google.com/forum/?fromgroups#!topic/clojure-dev/i7H82fJYL-U

Andy's request stated "Attached patch seems to have spelling mistakes, and perhaps could be worded more clearly."

I hope my new patch is an improvement upon what was there.

This patch supersedes '0001-Clarify-docstring-for-defmulti.patch' from 14/Sep/11.

Show
Scott Lowe added a comment - New patch: '0001-CLJ-835-Refine-doc-string-for-defmulti-hierarchy-opt.patch' 10/May/12. I've attached a new doc string patch in response to Andy Fingerhut's request posted here: https://groups.google.com/forum/?fromgroups#!topic/clojure-dev/i7H82fJYL-U Andy's request stated "Attached patch seems to have spelling mistakes, and perhaps could be worded more clearly." I hope my new patch is an improvement upon what was there. This patch supersedes '0001-Clarify-docstring-for-defmulti.patch' from 14/Sep/11.
Scott Lowe made changes -
Scott Lowe made changes -
Patch Code [ 10001 ]
Rich Hickey made changes -
Approval Vetted [ 10003 ]
Fix Version/s Release 1.5 [ 10150 ]
Hide
Fogus added a comment -

This is a million times better than what was there before, but (who knew!?) it could be better. A couple points of contention:

  • The order under the :hierarchy 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.
  • In the isa? example it would be great to show the return value.
  • 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?
  • It's ok to finish with a very small example of its use in defmethod, in fact a simple example specifying methods for ::shape and ::circle would clarify the intent nicely.
Show
Fogus added a comment - This is a million times better than what was there before, but (who knew!?) it could be better. A couple points of contention:
  • The order under the :hierarchy 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.
  • In the isa? example it would be great to show the return value.
  • 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?
  • It's ok to finish with a very small example of its use in defmethod, in fact a simple example specifying methods for ::shape and ::circle would clarify the intent nicely.
Fogus made changes -
Approval Vetted [ 10003 ] Incomplete [ 10006 ]
Hide
Rich Hickey added a comment -

Please leave examples out of docs strings. Use precise language.

Show
Rich Hickey added a comment - Please leave examples out of docs strings. Use precise language.
Rich Hickey made changes -
Fix Version/s Release 1.5 [ 10150 ]
Alex Miller made changes -
Approval Incomplete [ 10006 ]
Alex Miller made changes -
Approval Triaged [ 10120 ]
Alex Miller made changes -
Labels docstring
Rich Hickey made changes -
Approval Triaged [ 10120 ] Vetted [ 10003 ]
Fix Version/s Release 1.6 [ 10157 ]
Hide
Alex Miller added a comment -

I don't think this patch has been updated since Rich's last comment, so moving to Incomplete (not ready to screen).

Show
Alex Miller added a comment - I don't think this patch has been updated since Rich's last comment, so moving to Incomplete (not ready to screen).
Alex Miller made changes -
Approval Vetted [ 10003 ] Incomplete [ 10006 ]
Hide
Fogus added a comment -

Refined language around defmulti hierarchies and removed examples per RH's request.

Show
Fogus added a comment - Refined language around defmulti hierarchies and removed examples per RH's request.
Alex Miller made changes -
Approval Incomplete [ 10006 ] Vetted [ 10003 ]
Alex Miller made changes -
Description The :hierarchy option for defmulti should be passed a var, but this is not mentioned in the doc string.

The error message from passing the hierarchy directly is rather cryptic:

Evaluation aborted on java.lang.ClassCastException: clojure.lang.PersistentArrayMap cannot be cast to clojure.lang.IRef (SOURCE_FORM_44:19).
The :hierarchy option for defmulti should be passed a var, but this is not mentioned in the doc string.

The error message from passing the hierarchy directly is rather cryptic:

{code}
Evaluation aborted on java.lang.ClassCastException: clojure.lang.PersistentArrayMap cannot be cast to clojure.lang.IRef (SOURCE_FORM_44:19).
{code}

*Patch:* 0001-CLJ-835-ReRefine-doc-string-for-defmulti-removing-examples-and-solidifying-language.patch

*Screened by:*
Alex Miller made changes -
Approval Vetted [ 10003 ] Screened [ 10004 ]
Description The :hierarchy option for defmulti should be passed a var, but this is not mentioned in the doc string.

The error message from passing the hierarchy directly is rather cryptic:

{code}
Evaluation aborted on java.lang.ClassCastException: clojure.lang.PersistentArrayMap cannot be cast to clojure.lang.IRef (SOURCE_FORM_44:19).
{code}

*Patch:* 0001-CLJ-835-ReRefine-doc-string-for-defmulti-removing-examples-and-solidifying-language.patch

*Screened by:*
The :hierarchy option for defmulti should be passed a var, but this is not mentioned in the doc string.

The error message from passing the hierarchy directly is rather cryptic:

{code}
Evaluation aborted on java.lang.ClassCastException: clojure.lang.PersistentArrayMap cannot be cast to clojure.lang.IRef (SOURCE_FORM_44:19).
{code}

*After:*

{code}
user=> (doc defmulti)
-------------------------
clojure.core/defmulti
([name docstring? attr-map? dispatch-fn & options])
Macro
  Creates a new multimethod with the associated dispatch function.
  The docstring and attribute-map are optional.

  Options are key-value pairs and may be one of:

  :default

  The default dispatch value, defaults to :default

  :hierarchy

  The value used for hierarchical dispatch (e.g. ::square is-a ::shape)

  Hierarchies are type-like relationships that do not depend upon type
  inheritance. By default Clojure's multimethods dispatch off of a
  global hierarchy map. However, a hierarchy relationship can be
  created with the derive function used to augment the root ancestor
  created with make-hierarchy.

  Multimethods expect the value of the hierarchy option to be supplied as
  a reference type e.g. a var (i.e. via the Var-quote dispatch macro #'
  or the var special form).
{code}

*Patch:* 0001-CLJ-835-ReRefine-doc-string-for-defmulti-removing-examples-and-solidifying-language.patch

*Screened by:* Alex Miller
Rich Hickey made changes -
Approval Screened [ 10004 ] Ok [ 10007 ]
Stuart Halloway made changes -
Resolution Completed [ 1 ]
Status Open [ 1 ] Closed [ 6 ]

People

Vote (1)
Watch (2)

Dates

  • Created:
    Updated:
    Resolved: