Clojure

Documentation for extend-type falsely implies that & is allowed in protocol fn signatures

Details

  • Type: Defect Defect
  • Status: Closed Closed
  • Priority: Trivial Trivial
  • Resolution: Declined
  • Affects Version/s: None
  • Fix Version/s: Release 1.6
  • Component/s: None
  • Labels:
  • Patch:
    Code
  • Approval:
    Vetted

Description

The documentation for extend-type contains the following example:

(extend-type MyType 
    Countable
      (cnt [c] ...)
    Foo
      (bar [x y] ...)
      (baz ([x] ...) ([x y & zs] ...)))

However, [x y & zs] is not a valid parameter list for a protocol fn. The documentation should be appropriately amended.

Activity

Hide
John Szakmeister added a comment -

v2 of the patch is simply converts the patch to git format. I made sure that Mr. Duffy got proper attribution. I also took a stab at a simple log message. Any problems with the latter are mine, and I'm happy to fix it up if necessary.

Show
John Szakmeister added a comment - v2 of the patch is simply converts the patch to git format. I made sure that Mr. Duffy got proper attribution. I also took a stab at a simple log message. Any problems with the latter are mine, and I'm happy to fix it up if necessary.
John Szakmeister made changes -
Field Original Value New Value
Attachment extended-type-doc-fix-v2.patch [ 11257 ]
Rich Hickey made changes -
Approval Vetted [ 10003 ]
Fix Version/s Release 1.5 [ 10150 ]
Hide
Aaron Bedra added a comment -

This doesn't update the entire doc string. The expansion is updated, but the signature section isn't. Here's what shows up.

user=> (doc extend-type)
-------------------------
clojure.core/extend-type
([t & specs])
Macro
  A macro that expands into an extend call. Useful when you are
  supplying the definitions explicitly inline, extend-type
  automatically creates the maps required by extend.  Propagates the
  class as a type hint on the first argument of all fns.

  (extend-type MyType 
    Countable
      (cnt [c] ...)
    Foo
      (bar [x y] ...)
      (baz ([x] ...) ([x y & zs] ...)))

  expands into:

  (extend MyType
   Countable
     {:cnt (fn [c] ...)}
   Foo
     {:baz (fn ([x] ...) ([x y ...] ...))
      :bar (fn [x y] ...)})
Show
Aaron Bedra added a comment - This doesn't update the entire doc string. The expansion is updated, but the signature section isn't. Here's what shows up.
user=> (doc extend-type)
-------------------------
clojure.core/extend-type
([t & specs])
Macro
  A macro that expands into an extend call. Useful when you are
  supplying the definitions explicitly inline, extend-type
  automatically creates the maps required by extend.  Propagates the
  class as a type hint on the first argument of all fns.

  (extend-type MyType 
    Countable
      (cnt [c] ...)
    Foo
      (bar [x y] ...)
      (baz ([x] ...) ([x y & zs] ...)))

  expands into:

  (extend MyType
   Countable
     {:cnt (fn [c] ...)}
   Foo
     {:baz (fn ([x] ...) ([x y ...] ...))
      :bar (fn [x y] ...)})
Aaron Bedra made changes -
Approval Vetted [ 10003 ] Incomplete [ 10006 ]
Hide
Tassilo Horn added a comment -

This is very much related to http://dev.clojure.org/jira/browse/CLJ-1024.

NOTE: While varargs are not supported in protocol declarations, dynamic extension of a protocol via extend (extend-type, extend-protocol) does allow for varargs and also destructuring, cause the method impls are actually normal clojure functions.

So if a Foo protocol declares a (foo [this a b c]) method, you can extend/extend-type/extend-protocol it dynamically using (foo [this & more] (do-magick)) where `a b c` are conflated into the `more` parameter.

However, that doesn't work for method implementations defined by deftype, defrecord, and reify.

So with respect to the facts, the example in the docstring is actually correct, so I'm not sure if it should be changed. However, what's supported in which cases should be documented better as it is right now.

Show
Tassilo Horn added a comment - This is very much related to http://dev.clojure.org/jira/browse/CLJ-1024. NOTE: While varargs are not supported in protocol declarations, dynamic extension of a protocol via extend (extend-type, extend-protocol) does allow for varargs and also destructuring, cause the method impls are actually normal clojure functions. So if a Foo protocol declares a (foo [this a b c]) method, you can extend/extend-type/extend-protocol it dynamically using (foo [this & more] (do-magick)) where `a b c` are conflated into the `more` parameter. However, that doesn't work for method implementations defined by deftype, defrecord, and reify. So with respect to the facts, the example in the docstring is actually correct, so I'm not sure if it should be changed. However, what's supported in which cases should be documented better as it is right now.
Rich Hickey made changes -
Fix Version/s Release 1.5 [ 10150 ]
Hide
Alex Miller added a comment -

Putting back in triage to go through release assignment again.

Show
Alex Miller added a comment - Putting back in triage to go through release assignment again.
Alex Miller made changes -
Approval Incomplete [ 10006 ] Triaged [ 10120 ]
Alex Miller made changes -
Labels documentation docstring
Rich Hickey made changes -
Approval Triaged [ 10120 ] Vetted [ 10003 ]
Fix Version/s Release 1.6 [ 10157 ]
Stuart Halloway made changes -
Assignee Stuart Halloway [ stu ]
Hide
Stuart Halloway added a comment -

I agree with Tassilo's comment, the documented behavior works. You can't use varargs in defprotocol but you can use them in extend-type.

Show
Stuart Halloway added a comment - I agree with Tassilo's comment, the documented behavior works. You can't use varargs in defprotocol but you can use them in extend-type.
Stuart Halloway made changes -
Resolution Declined [ 2 ]
Status Open [ 1 ] Closed [ 6 ]

People

Vote (0)
Watch (2)

Dates

  • Created:
    Updated:
    Resolved: