Description
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() {}
}