scaladoc is not uptodate with latest release?

[Zemian Deng]

Hi list,

1) The online scaladoc
http://www.scala-lang.org/docu/files/api/index.html says for
2.7.1-final, but I just found out that scala.collection.mutable.Map
has deprecated method += that's not showing on scaladoc. Can we have a
matching doc?

2) I like the old deprecated method better than the new suggested way.
Is there better reason for this change other than require more typing?
val m = new HashMap[String, Int]
m += "one"->111 //warning: there were deprecation warnings; re-run
with -deprecation for details
m += Pair("two", 222) //the new way
m += ("two", 222) // and this product error!

What is your take on the deprecated method?
-Z

[Darshan Shaligram-2]

On Fri, Jun 20, 2008 at 12:11 AM, Zemian Deng <keepitsimple12@...> wrote:

> 1) The online scaladoc
> http://www.scala-lang.org/docu/files/api/index.html says for
> 2.7.1-final, but I just found out that scala.collection.mutable.Map
> has deprecated method += that's not showing on scaladoc. Can we have a
> matching doc?

The docs are correct. There are two += methods, and you happen to be
using the wrong (deprecated) one.

> 2) I like the old deprecated method better than the new suggested way.
> Is there better reason for this change other than require more typing?
> val m = new HashMap[String, Int]
> m += "one"->111 //warning: there were deprecation warnings; re-run
> with -deprecation for details

Try m += ("one" -> 111)

 m += "one"->111  is the same as    m.+=("one").->(111)  - this usage
of += is deprecated
 m += ("one" -> 111)   is the same as    m.+=("one" -> 111)    - this is fine.

Once the precedence of the += operator method is fixed (in 2.7.2?),
this problem will go away - you'll have to make a deliberate effort to
invoke the deprecated case.

> m += ("two", 222) // and this product error!

Because you're calling m.+=("two", 222), passing two arguments to +=
where it wants just one.

Cheers,
Darshan

[Thomas Chust]

Zemian Deng wrote:

> [...] I just found out that scala.collection.mutable.Map
> has deprecated method += that's not showing on scaladoc. [...]

Hello,

the method +=(key: A): MapTo that you refer to is documented and
correctly marked as deprecated in the released scaladoc.

> [...] I like the old deprecated method better than the new suggested way.
> Is there better reason for this change other than require more typing?

I think you are simply experiencing trouble with operator precedence and
ambiguity of parentheses here.

> val m = new HashMap[String, Int]
> m += "one"->111 // warning: [...]

Try

   m += ("one" -> 111)

> m += Pair("two", 222) //the new way
> m += ("two", 222) // and this product error!

Try

   m += (("one", 111))

> What is your take on the deprecated method?

I fully agree that having a method named += which doesn't add an element
to a collection but rather returns some strange object that is capable
of performing the addition via its method called -> is a bad idea and
rather counterintuitive. The new solution to take a Tuple2 as a
parameter and to have the implicit conversion from Any to ArrowAssoc is
much more to my taste.

cu,
Thomas

[Zemian Deng]

Ahh, thank you both Thomas and Darshan. It make more sense now.

For the scaladoc, the @depreated is NOT stated under summary section,
but it's in the detail section of the method instead, which I missed
it. Thanks again for correcting me. I do wish the "deprecated" is
added to Summary section as well though( I think javadoc does this.)

Cheers,
-Z

On Thu, Jun 19, 2008 at 3:04 PM, Thomas Chust <chust@...> wrote:

> Zemian Deng wrote:
>
>> [...] I just found out that scala.collection.mutable.Map
>> has deprecated method += that's not showing on scaladoc. [...]
>
> Hello,
>
> the method +=(key: A): MapTo that you refer to is documented and correctly
> marked as deprecated in the released scaladoc.
>
>> [...] I like the old deprecated method better than the new suggested way.
>> Is there better reason for this change other than require more typing?
>
> I think you are simply experiencing trouble with operator precedence and
> ambiguity of parentheses here.
>
>> val m = new HashMap[String, Int]
>> m += "one"->111 // warning: [...]
>
> Try
>
>  m += ("one" -> 111)
>
>> m += Pair("two", 222) //the new way
>> m += ("two", 222) // and this product error!
>
> Try
>
>  m += (("one", 111))
>
>> What is your take on the deprecated method?
>
> I fully agree that having a method named += which doesn't add an element to
> a collection but rather returns some strange object that is capable of
> performing the addition via its method called -> is a bad idea and rather
> counterintuitive. The new solution to take a Tuple2 as a parameter and to
> have the implicit conversion from Any to ArrowAssoc is much more to my
> taste.
>
> cu,
> Thomas
>

[Thomas Chust]

Zemian Deng wrote:

> [...]
> For the scaladoc, the @depreated is NOT stated under summary section,
> but it's in the detail section of the method instead,
> [...]

Hello,

I also think it's useful to see the deprecation annotation in the
overview section of the documentation.

You could try the new vscaladoc which does mark deprecated methods by
striking out their names in the overview section :-)

cu,
Thomas

[Zemian Deng]

I just checked, and it doesn't stike += for some reason. Is it because
its operator char?

-Z

On 6/19/08, Thomas Chust <chust@...> wrote:

> Zemian Deng wrote:
>
>> [...]
>> For the scaladoc, the @depreated is NOT stated under summary section,
>> but it's in the detail section of the method instead,
>> [...]
>
> Hello,
>
> I also think it's useful to see the deprecation annotation in the
> overview section of the documentation.
>
> You could try the new vscaladoc which does mark deprecated methods by
> striking out their names in the overview section :-)
>
> cu,
> Thomas
>