<< Back to previous view

[CLJ-980] Documentation for extend-type falsely implies that & is allowed in protocol fn signatures Created: 03/May/12  Updated: 18/Oct/13  Resolved: 18/Oct/13

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: None
Fix Version/s: Release 1.6

Type: Defect Priority: Trivial
Reporter: Charles Duffy Assignee: Stuart Halloway
Resolution: Declined Votes: 0
Labels: docstring

Attachments: File clojure--extend-type-doc-fix.diff     Text File extended-type-doc-fix-v2.patch    
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.



 Comments   
Comment by John Szakmeister [ 25/May/12 4:00 AM ]

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.

Comment by Aaron Bedra [ 15/Aug/12 10:08 PM ]

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] ...)})
Comment by Tassilo Horn [ 25/Aug/12 6:44 AM ]

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.

Comment by Alex Miller [ 28/Jul/13 10:13 PM ]

Putting back in triage to go through release assignment again.

Comment by Stuart Halloway [ 18/Oct/13 9:31 AM ]

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.

Generated at Wed Aug 20 13:30:23 CDT 2014 using JIRA 4.4#649-r158309.