Provide a built-in macro that copies the documentation of the superclass

[mateusfccp]

I looked for something like this in the issues but couldn't find anything.

Problem

Currently, if you have an interface A with a member a documented with doc(a), an interface B implementing A will inherit the documentation doc(a) for its a implementation unless it explicitly document the method.

For instance:

// foo.dart
class Foo {
  /// Bars the foo.
  void bar() {}

  /// Quxes the foo.
  void qux() {}
}

// baz.dart

import 'foo.dart';

class Baz extends Foo {
  @override
  void bar() {}

  /// Quxes the baz.
  @override
  void qux() {}
}

In this case, Baz.bar will have the same documentation as Foo.bar, but Baz.qux will have the documentation it specified instead of Foo.qux's one.

However, sometimes we want to add to the superclass documentation instead of overwriting it. If you own the library that defines the interface you are implementing, you can use a template:

// library_that_i_own.dart
class Foo {
  /// {@template foo.bar}
  /// Bars the foo.
  /// {@endtemplate}
  void bar() {}
}

// my_library.dart

import 'library_that_i_own.dart';

class Baz extends Foo {
  /// {@macro foo.bar}
  ///
  /// After barring, also bazes the Foo.
  @override
  void bar() {}
}

This is not possible, however, if you are implementing an interface that you don't own.

Suggestion

Implement a built-in macro that refers to the documentation of the supertype. For instance, {@macro super} or make it a different "command", like {@super} (so it's not breaking if someone ever defined a template called super).

The aforementioned would then be implemented like this:

// library_that_i_dont_own.dart
class Foo {
  /// Bars the foo.
  void bar() {}
}

// my_library.dart

import 'library_that_i_dont_own.dart';

class Baz extends Foo {
  /// {@super}
  ///
  /// After barring, also bazes the Foo.
  @override
  void bar() {}
}

[mateusfccp]

If there's any interest in reviewing a PR for this, I may do it.

[srawlins]

If we implement this feature (or accept a PR for it), it will take place in the analyzer, so that it is supported in IDEs as well.

Let me bring this up in an analyzer team meeting, and I'll post back here on whether we like it (personally I like it; I'm surprised it hasn't come up before, that I've seen).