Site-www: Language tour should explain that != calls operator ==

[kwalrath]

_From @detreville on September 26, 2017 19:3_

Look at this code:

class A {
  bool operator==(A other) {
    return false;
  }
}

main() {
  A a = new A();
  print(a == a);
  print(a != a);
}

Straightforward.

Here, the expression a != a calls A's operator==. I can't find ANYWHERE in the Dart docs that says so. If this fact is indeed missing, it would be very nice to add.

_Copied from original issue: dart-lang/sdk#30896_

[kwalrath]

_From @lrhn on September 28, 2017 9:28_

The specification says:

An equality expression of the form e1 != e2 is equivalent to the expression
!(e1 == e2). An equality expression of the form super != e is equivalent to the
expression !(super == e).

It's likely true that we don't say that anywhere else.

[kwalrath]

_From @eernstg on September 28, 2017 9:46_

Thanks for the input! I think Lasse's excerpt shows that the language specification does make this fact explicit, but I also think that it would be useful to have it mentioned here: https://www.dartlang.org/guides/language/language-tour#overridable-operators. So I'll change the label to area-documentation and suggest such a change.

I think it would suffice to add something like this, just before For more information on overriding:

You may have noticed that `!=` is not an overridable operator. This is because
`!=` is not an operator in its own right, the expression `e1 != e2` is just syntactic
sugar for `!(e1 == e2)`.

Changing assignee, to match area-documentation.

[kwalrath]

_From @detreville on September 29, 2017 0:6_

Thanks. I had tried Googling for this but it took me a couple of days of
doing so until I found it this morning, after I thought to add "spec" to my
search.

I haven't followed the link in the email above yet but I imagine it's to
the ECMA spec I found this morning.

I did not mean to suggest this fact was completely undocumented, only that
the documentation was not readily discoverable. Adding it to the Language
Tour would no doubt fix this. The Language Tour is of course meant as a
high-level document, while the spec is very detailed; it's unfortunate that
there seems to be nothing in-between.

Googling for 'dart "operator =="' does list the Language Tour on the first
page, amid a bunch of less interesting hits. Curiously, so does searching
for 'dart "operator !="' ! In either case, the spec does not appear until
far below.

BTW, I work at Google. I had initially filed this bug at Google, then
refiled it here. I think it probably got a little garbled in the refiling.

Thanks!

Cheers,
John

[kwalrath]

_From @lrhn on September 29, 2017 7:25_

One thing we could do is to mention it in the Object.== operator documentation.
It's still not possible to look up != directly, but finding == is probably the next thing a user will try.

[kwalrath]

_From @eernstg on September 29, 2017 8:40_

I haven't followed the link in the email above yet but I imagine it's to the ECMA spec I found this morning.

The ECMA spec is a number of steps behind the development of the language. The bleeding edge spec can be found at https://github.com/dart-lang/sdk/blob/master/docs/language/dartLangSpec.tex.

[kwalrath]

_From @detreville on October 2, 2017 21:25_

Excellent; thanks!

Cheers,
John

On Fri, Sep 29, 2017 at 1:41 AM Erik Ernst [e-mail] wrote:

I haven't followed the link in the email above yet but I imagine it's to
the ECMA spec I found this morning.

The ECMA spec is a number of steps behind the development of the language.
The bleeding edge spec can be found at
https://github.com/dart-lang/sdk/blob/master/docs/language/dartLangSpec.tex
.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/dart-lang/sdk/issues/30896#issuecomment-333067871,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAYXMoKGa2waQ1xEBix1bqc8fiT6wyMPks5snK0egaJpZM4Pkuo3
.

>

Cheers,
John

[mzaman07]

Hello

I'm new to this repo and I see this issue is marked as beginner friendly so I would like to help.

mzaman

[kwalrath]

Go ahead, @mzaman07! Click the GitHub link from the page, then make your edits and create a PR. Thanks!

[mzaman07]

Should this be marked with a warning label or a note label? Also is there an API type of doc/other documentation that tells you what is an overridable operator or not?

[kwalrath]

I'd use either a note or an ordinary paragraph immediately following the table in https://www.dartlang.org/guides/language/language-tour#overridable-operators.

I think only the language spec covers what's overridable.

[kwalrath]

Fixed by #1166.