Wrong link for `operator ==` in dartdoc for class `int` and `double`

[eernstg]

Consider the double class dartdoc, operator ==: This operator is inherited, and the entry for the operator links to the operator == of Object. The same is true for the int class dartdoc.

However, this link is misleading because the inherited implementation comes from num and not from Object (and I believe these links are supposed to point to the inherited implementation, not just to an arbitrary implementation in a superclass).

The issue may arise because of the substantial amount of special casing that applies for operator == and for the classes int and double, but it would still be better if we could have a link to the operator == in num from the pages about int and double.

[jcollins-g]

Elevating to P1 based on our triage priorities (incorrect linkage, few or on edge cases)

This may be related to other inheritance chain problems @srawlins has been looking at.

[jcollins-g]

Started looking at this one today. Looks to be a construction problem with class int in Dartdoc -- it's actually getting the operator from Object even though the operator in num is available.

[jcollins-g]

@eernstg If I understand correctly what's happening here, there is a "hidden" implementation for num that is not visible in Dart source code?

[eernstg]

Yes, it is not easy to see what's going on.

For instance, the vm implementation of operator == for double is here and the one for integers is here, so it is added by the patch mechanism.

The declaration in num is here, and it's abstract (so dartdoc should presumably ignore it for the purposes of linking to an inherited implementation).

For compilation to JavaScript, there is only an implementation for _BigIntImpl, and equality for numbers (int and double, both represented as JavaScript numbers) would probably use JavaScript operators directly.

Dartdoc could hardly rely on the result of patching the system libraries: this result differs for different target platforms, and they don't even agree on which classes have an implementation and which ones will use an inherited implementation.

I think this implies that operator == on numbers, and probably a few other "system" methods, will have to be treated as special cases, because they just don't follow normal rules. ;-)

[jcollins-g]

@eernstg There appear to be a fair number of these in the SDK. I modified dartdoc using the fix in #2449 to detect this situation and there are 24 of them, though most are in private libraries:

** implementation hack detected in Library dart:collection.DoubleLinkedQueue.cast : 
**   Iterable<R> cast<R>() (abstract class Iterable<E>) 
**      redirect to => Queue<R> cast<R>() (abstract class Queue<E> implements EfficientLengthIterable<E>)
** implementation hack detected in Library dart:collection.ListQueue.cast : 
**   Iterable<R> cast<R>() (abstract class Iterable<E>) 
**      redirect to => Queue<R> cast<R>() (abstract class Queue<E> implements EfficientLengthIterable<E>)
** implementation hack detected in Library dart:core.double.== : 
**   bool ==(Object other) (class Object) 
**      redirect to => bool ==(Object other) (abstract class num implements Comparable<num>)
** implementation hack detected in Library dart:core.double.toString : 
**   String toString() (class Object) 
**      redirect to => String toString() (abstract class num implements Comparable<num>)
** implementation hack detected in Library dart:core.double.hashCode : 
**   int get hashCode (class Object) 
**      redirect to => int get hashCode (abstract class num implements Comparable<num>)
** implementation hack detected in Library dart:core.int.== : 
**   bool ==(Object other) (class Object) 
**      redirect to => bool ==(Object other) (abstract class num implements Comparable<num>)
** implementation hack detected in Library dart:core.int.toString : 
**   String toString() (class Object) 
**      redirect to => String toString() (abstract class num implements Comparable<num>)
** implementation hack detected in Library dart:core.int.hashCode : 
**   int get hashCode (class Object) 
**      redirect to => int get hashCode (abstract class num implements Comparable<num>)
** implementation hack detected in Library dart:_http._HttpClientRequest.close : 
**   Future<dynamic> close() (class _StreamSinkImpl<T> implements StreamSink<T>) 
**      redirect to => Future<HttpClientResponse> close() (abstract class HttpClientRequest implements IOSink)
** implementation hack detected in Library dart:_http._HttpClientRequest.done : 
**   Future<dynamic> get done (class _StreamSinkImpl<T> implements StreamSink<T>) 
**      redirect to => Future<HttpClientResponse> get done (abstract class HttpClientRequest implements IOSink)
** implementation hack detected in Library dart:_native_typed_data.NativeFloat32x4List.sublist : 
**   List<Float32x4> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Float32x4List sublist(int start, [int? end]) (abstract class Float32x4List implements List<Float32x4>, TypedData)
** implementation hack detected in Library dart:_native_typed_data.NativeInt32x4List.sublist : 
**   List<Int32x4> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Int32x4List sublist(int start, [int? end]) (abstract class Int32x4List implements List<Int32x4>, TypedData)
** implementation hack detected in Library dart:_native_typed_data.NativeFloat64x2List.sublist : 
**   List<Float64x2> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Float64x2List sublist(int start, [int? end]) (abstract class Float64x2List implements List<Float64x2>, TypedData)
** implementation hack detected in Library dart:_native_typed_data.NativeFloat32List.sublist : 
**   List<double> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Float32List sublist(int start, [int? end]) (abstract class Float32List implements List<double>, _TypedFloatList)
** implementation hack detected in Library dart:_native_typed_data.NativeFloat64List.sublist : 
**   List<double> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Float64List sublist(int start, [int? end]) (abstract class Float64List implements List<double>, _TypedFloatList)
** implementation hack detected in Library dart:_native_typed_data.NativeInt16List.sublist : 
**   List<int> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Int16List sublist(int start, [int? end]) (abstract class Int16List implements List<int>, _TypedIntList)
** implementation hack detected in Library dart:_native_typed_data.NativeInt32List.sublist : 
**   List<int> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Int32List sublist(int start, [int? end]) (abstract class Int32List implements List<int>, _TypedIntList)
** implementation hack detected in Library dart:_native_typed_data.NativeInt8List.sublist : 
**   List<int> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Int8List sublist(int start, [int? end]) (abstract class Int8List implements List<int>, _TypedIntList)
** implementation hack detected in Library dart:_native_typed_data.NativeUint16List.sublist : 
**   List<int> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Uint16List sublist(int start, [int? end]) (abstract class Uint16List implements List<int>, _TypedIntList)
** implementation hack detected in Library dart:_native_typed_data.NativeUint32List.sublist : 
**   List<int> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Uint32List sublist(int start, [int? end]) (abstract class Uint32List implements List<int>, _TypedIntList)
** implementation hack detected in Library dart:_native_typed_data.NativeUint8ClampedList.sublist : 
**   List<int> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Uint8ClampedList sublist(int start, [int? end]) (abstract class Uint8ClampedList implements List<int>, _TypedIntList)
** implementation hack detected in Library dart:_native_typed_data.NativeUint8List.sublist : 
**   List<int> sublist(int start, [int end]) (abstract class ListMixin<E> implements List<E>) 
**      redirect to => Uint8List sublist(int start, [int? end]) (abstract class Uint8List implements List<int>, _TypedIntList)
** implementation hack detected in Library dart:_internal.CastSet.cast : 
**   Iterable<R> cast<R>() (abstract class Iterable<E>) 
**      redirect to => Set<R> cast<R>() (abstract class Set<E> extends EfficientLengthIterable<E>)
** implementation hack detected in Library dart:_internal.CastQueue.cast : 
**   Iterable<R> cast<R>() (abstract class Iterable<E>) 
**      redirect to => Queue<R> cast<R>() (abstract class Queue<E> implements EfficientLengthIterable<E>)

It would be nice if there was a common way tooling could detect these hacks and behave appropriately. While the method I have works it currently depends on idiosyncracies of the analyzer implementation that I'd prefer not to rely on.

[eernstg]

The link for an inherited member m in a DartDoc class page should probably take the reader to a DartDoc comment for m in a superclass where there is a non-trivial change to the "contract" of m, because that's what a developer who may wish to call m really needs to know.

(By "contract" I mean the informal semantics of the member: What needs to be true before it can be called, and what it will then ensure if and when it returns. That's the information that any caller needs to be aware of.)

I think the contract should actually be considered more important than whether or not there is a concrete declaration (that is, an implementation) of m at that location.

So let's say that we can ensure that exactly those class members that introduce a new contract have a DartDoc comment. This is probably almost precisely true already, because this means that we'll write a DartDoc comment when there is something important to write in it, and we won't write anything when the nearest superclass DartDoc is still valid.

We would then let the 'inherited' link point to the nearest superclass DartDoc, no matter whether it's on an abstract or a concrete declaration.

It's always possible to add an additional abstract declaration (for instance, in the system libraries, but also in any other library) in the case where there is a need to have a DartDoc comment. So we may need to edit the source code in order to put the DartDoc comments in just the right places, according to this usage. But it seems useful and meaningful to have source code where this approach is used.

@jcollins-g, wouldn't this approach allow you to get rid of the special casing? For instance, we wouldn't worry about the fact that one platform adds an operator == to both int and double, and another one does neither, because we will simply use the DartDoc comment from num for both of them, as we should anyway!