Make dartdoc warnings fatal (& cleanup of warnings) (flutter#62367)

flutter-rosita · Jul 28, 2020 · f4e10b4 · f4e10b4
1 parent e17a721
commit f4e10b4
Show file tree

Hide file tree

Showing 40 changed files with 177 additions and 209 deletions.
diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml
@@ -13,9 +13,24 @@ dartdoc:
       command: ["dev/snippets/lib/main.dart", "--type=sample", "--dartpad"]
       description: "Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad."
   errors:
-    - tool-error  # enabled by default
-    - duplicate-file  # enabled by default
-    - invalid-parameter  # enabled by default
-    - unresolved-export  # enabled by default
-    - unknown-macro  # a {@macro foo} reference cannot be resolved
-    - invalid-parameter  # an invalid parameter is passed to a {@foo x y} directive
+    # The following are always errors:
+    - duplicate-file
+    - invalid-parameter
+    - tool-error
+    - unresolved-export
+    # The following are elevated from warnings because we currently don't
+    # fail on warnings:
+    - ambiguous-doc-reference
+    - ambiguous-reexport
+    - ignored-canonical-for
+    - no-canonical-found
+    - not-implemented
+    - no-library-level-docs
+    - category-order-gives-missing-package-name
+    - reexported-private-api-across-packages
+    # - unresolved-doc-reference # Too many failures, needs clean-up
+    - broken-link
+    - unknown-macro
+    - orphaned-file
+    - unknown-file
+    - missing-from-search-index
diff --git a/dev/tools/dartdoc.dart b/dev/tools/dartdoc.dart
@@ -144,12 +144,7 @@ Future<void> main(List<String> arguments) async {
     '--footer-text', 'lib/footer.html',
     '--allow-warnings-in-packages',
     <String>[
-      'Flutter',
       'flutter',
-      'platform_integration',
-      'flutter_test',
-      'flutter_driver',
-      'flutter_localizations',
     ].join(','),
     '--exclude-packages',
     <String>[

diff --git a/packages/flutter/lib/src/gestures/binding.dart b/packages/flutter/lib/src/gestures/binding.dart
@@ -229,11 +229,6 @@ mixin GestureBinding on BindingBase implements HitTestable, HitTestDispatcher, H
 
 /// Variant of [FlutterErrorDetails] with extra fields for the gesture
 /// library's binding's pointer event dispatcher ([GestureBinding.dispatchEvent]).
-///
-/// See also:
-///
-///  * [FlutterErrorDetailsForPointerRouter], which is also used by the
-///    gesture library.
 class FlutterErrorDetailsForPointerEventDispatcher extends FlutterErrorDetails {
   /// Creates a [FlutterErrorDetailsForPointerEventDispatcher] object with the given
   /// arguments setting the object's properties.

diff --git a/packages/flutter/lib/src/painting/borders.dart b/packages/flutter/lib/src/painting/borders.dart
@@ -81,7 +81,7 @@ class BorderSide {
   ///
   /// If one of the sides is zero-width with [BorderStyle.none], then the other
   /// side is return as-is. If both of the sides are zero-width with
-  /// [BorderStyle.none], then [BorderSide.zero] is returned.
+  /// [BorderStyle.none], then [BorderSide.none] is returned.
   ///
   /// The arguments must not be null.
   static BorderSide merge(BorderSide a, BorderSide b) {

diff --git a/packages/flutter/lib/src/painting/clip.dart b/packages/flutter/lib/src/painting/clip.dart
@@ -6,7 +6,7 @@
 
 import 'dart:ui' show Canvas, Clip, Path, Paint, Rect, RRect;
 
-/// Clip utilities used by [PaintingContext] and [TestRecordingPaintingContext].
+/// Clip utilities used by [PaintingContext].
 abstract class ClipContext {
   /// The canvas on which to paint.
   Canvas get canvas;

diff --git a/packages/flutter/lib/src/painting/debug.dart b/packages/flutter/lib/src/painting/debug.dart
@@ -34,12 +34,12 @@ HttpClientProvider debugNetworkImageHttpClientProvider;
 
 typedef PaintImageCallback = void Function(ImageSizeInfo);
 
-/// Tracks the bytes used by a [ui.Image] compared to the bytes needed to paint
-/// that image without scaling it.
+/// Tracks the bytes used by a [dart:ui.Image] compared to the bytes needed to
+/// paint that image without scaling it.
 @immutable
 class ImageSizeInfo {
-  /// Creates an object to track the backing size of a [ui.Image] compared to
-  /// its display size on a [Canvas].
+  /// Creates an object to track the backing size of a [dart:ui.Image] compared
+  /// to its display size on a [Canvas].
   ///
   /// This class is used by the framework when it paints an image to a canvas
   /// to report to `dart:developer`'s [postEvent], as well as to the

diff --git a/packages/flutter/lib/src/painting/gradient.dart b/packages/flutter/lib/src/painting/gradient.dart
@@ -661,7 +661,7 @@ class RadialGradient extends Gradient {
   ///
   /// For example, if a radial gradient is painted on a box that is
   /// 100.0 pixels wide and 200.0 pixels tall, then a radius of 1.0
-  /// will place the 1.0 stop at 100.0 pixels from the [focus].
+  /// will place the 1.0 stop at 100.0 pixels from the [focal] point.
   ///
   /// If this value is specified and is greater than 0.0, either [focal] or
   /// [center] must not resolve to [Offset.zero], which would fail to create

diff --git a/packages/flutter/lib/src/painting/image_provider.dart b/packages/flutter/lib/src/painting/image_provider.dart
@@ -637,7 +637,7 @@ abstract class AssetBundleImageProvider extends ImageProvider<AssetBundleImageKe
   const AssetBundleImageProvider();
 
   /// Converts a key into an [ImageStreamCompleter], and begins fetching the
-  /// image using [loadAsync].
+  /// image.
   @override
   ImageStreamCompleter load(AssetBundleImageKey key, DecoderCallback decode) {
     InformationCollector collector;
@@ -802,8 +802,8 @@ class ResizeImage extends ImageProvider<_SizeAwareCacheKey> {
 ///
 /// The image will be cached regardless of cache headers from the server.
 ///
-/// When a network image is used on the Web platform, the [cacheWidth] and
-/// [cacheHeight] parameters of the [DecoderCallback] are ignored as the Web
+/// When a network image is used on the Web platform, the `cacheWidth` and
+/// `cacheHeight` parameters of the [DecoderCallback] are ignored as the Web
 /// engine delegates image decoding of network images to the Web, which does
 /// not support custom decode sizes.
 ///
@@ -977,7 +977,7 @@ class MemoryImage extends ImageProvider<MemoryImage> {
 ///
 /// When fetching an image provided by the app itself, use the [assetName]
 /// argument to name the asset to choose. For instance, consider a directory
-/// `icons` with an image `heart.png`. First, the [pubspec.yaml] of the project
+/// `icons` with an image `heart.png`. First, the `pubspec.yaml` of the project
 /// should specify its assets in the `flutter` section:
 ///
 /// ```yaml
@@ -1127,8 +1127,8 @@ class _ErrorImageCompleter extends ImageStreamCompleter {
 
 /// The exception thrown when the HTTP request to load a network image fails.
 class NetworkImageLoadException implements Exception {
-  /// Creates a [NetworkImageLoadException] with the specified http status
-  /// [code] and the [uri]
+  /// Creates a [NetworkImageLoadException] with the specified http [statusCode]
+  /// and [uri].
   NetworkImageLoadException({@required this.statusCode, @required this.uri})
       : assert(uri != null),
         assert(statusCode != null),

diff --git a/packages/flutter/lib/src/painting/image_stream.dart b/packages/flutter/lib/src/painting/image_stream.dart
@@ -213,8 +213,8 @@ class ImageChunkEvent with Diagnosticable {
 ///
 /// The [ImageCache] will consider an image to be live until the listener count
 /// drops to zero after adding at least one listener. The
-/// [addOnLastListenerRemovedCallback] method is used for tracking this
-/// information.
+/// [ImageStreamCompleter.addOnLastListenerRemovedCallback] method is used for
+/// tracking this information.
 ///
 /// See also:
 ///

diff --git a/packages/flutter/lib/src/painting/inline_span.dart b/packages/flutter/lib/src/painting/inline_span.dart
@@ -294,7 +294,7 @@ abstract class InlineSpan extends DiagnosticableTree {
 
   /// Returns the UTF-16 code unit at the given `index` in the flattened string.
   ///
-  /// This only accounts for the [TextSpan.text] values and ignores [PlaceholderSpans].
+  /// This only accounts for the [TextSpan.text] values and ignores [PlaceholderSpan]s.
   ///
   /// Returns null if the `index` is out of bounds.
   int codeUnitAt(int index) {

diff --git a/packages/flutter/lib/src/painting/text_painter.dart b/packages/flutter/lib/src/painting/text_painter.dart
@@ -54,9 +54,9 @@ class PlaceholderDimensions {
   /// See also:
   ///
   ///  * [baseline], the baseline to align to when using
-  ///    [ui.PlaceholderAlignment.baseline],
-  ///    [ui.PlaceholderAlignment.aboveBaseline],
-  ///    or [ui.PlaceholderAlignment.underBaseline].
+  ///    [dart:ui.PlaceholderAlignment.baseline],
+  ///    [dart:ui.PlaceholderAlignment.aboveBaseline],
+  ///    or [dart:ui.PlaceholderAlignment.belowBaseline].
   ///  * [baselineOffset], the distance of the alphabetic baseline from the upper
   ///    edge of the placeholder.
   final ui.PlaceholderAlignment alignment;
@@ -70,7 +70,7 @@ class PlaceholderDimensions {
   ///
   ///  * [ui.PlaceholderAlignment.baseline]
   ///  * [ui.PlaceholderAlignment.aboveBaseline]
-  ///  * [ui.PlaceholderAlignment.underBaseline]
+  ///  * [ui.PlaceholderAlignment.belowBaseline]
   ///  * [ui.PlaceholderAlignment.middle]
   final TextBaseline baseline;
 
@@ -318,7 +318,7 @@ class TextPainter {
   ///
   /// Omitting or providing null for any properties of [StrutStyle] will result in
   /// default values being used. It is highly recommended to at least specify a
-  /// [fontSize].
+  /// [StrutStyle.fontSize].
   ///
   /// See [StrutStyle] for details.
   /// {@endtemplate}

diff --git a/packages/flutter/lib/src/painting/text_style.dart b/packages/flutter/lib/src/painting/text_style.dart
@@ -285,7 +285,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// ```
 /// {@end-tool}
 ///
-/// To use a font family defined in a package, the [package] argument must be
+/// To use a font family defined in a package, the `package` argument must be
 /// provided. For instance, suppose the font declaration above is in the
 /// `pubspec.yaml` of a package named `my_package` which the app depends on.
 /// Then creating the TextStyle is done as follows:

diff --git a/packages/flutter/lib/src/rendering/binding.dart b/packages/flutter/lib/src/rendering/binding.dart
@@ -384,8 +384,7 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   /// sent to the GPU.
   ///
   /// 7. The semantics phase: All the dirty [RenderObject]s in the system have
-  /// their semantics updated (see [RenderObject.semanticsAnnotator]). This
-  /// generates the [SemanticsNode] tree. See
+  /// their semantics updated. This generates the [SemanticsNode] tree. See
   /// [RenderObject.markNeedsSemanticsUpdate] for further details on marking an
   /// object dirty for semantics.
   ///

diff --git a/packages/flutter/lib/src/scheduler/binding.dart b/packages/flutter/lib/src/scheduler/binding.dart
@@ -39,9 +39,9 @@ set timeDilation(double value) {
 /// common time base.
 typedef FrameCallback = void Function(Duration timeStamp);
 
-/// Signature for [Scheduler.scheduleTask] callbacks.
+/// Signature for [SchedulerBinding.scheduleTask] callbacks.
 ///
-/// The type argument `T` is the task's return value. Consider [void] if the
+/// The type argument `T` is the task's return value. Consider `void` if the
 /// task does not return a value.
 typedef TaskCallback<T> = T Function();
 
@@ -138,14 +138,14 @@ class _FrameCallbackEntry {
 ///    to generate a frame.
 enum SchedulerPhase {
   /// No frame is being processed. Tasks (scheduled by
-  /// [WidgetsBinding.scheduleTask]), microtasks (scheduled by
+  /// [SchedulerBinding.scheduleTask]), microtasks (scheduled by
   /// [scheduleMicrotask]), [Timer] callbacks, event handlers (e.g. from user
   /// input), and other callbacks (e.g. from [Future]s, [Stream]s, and the like)
   /// may be executing.
   idle,
 
   /// The transient callbacks (scheduled by
-  /// [WidgetsBinding.scheduleFrameCallback]) are currently executing.
+  /// [SchedulerBinding.scheduleFrameCallback]) are currently executing.
   ///
   /// Typically, these callbacks handle updating objects to new animation
   /// states.
@@ -161,14 +161,14 @@ enum SchedulerPhase {
   midFrameMicrotasks,
 
   /// The persistent callbacks (scheduled by
-  /// [WidgetsBinding.addPersistentFrameCallback]) are currently executing.
+  /// [SchedulerBinding.addPersistentFrameCallback]) are currently executing.
   ///
   /// Typically, this is the build/layout/paint pipeline. See
   /// [WidgetsBinding.drawFrame] and [SchedulerBinding.handleDrawFrame].
   persistentCallbacks,
 
   /// The post-frame callbacks (scheduled by
-  /// [WidgetsBinding.addPostFrameCallback]) are currently executing.
+  /// [SchedulerBinding.addPostFrameCallback]) are currently executing.
   ///
   /// Typically, these callbacks handle cleanup and scheduling of work for the
   /// next frame.
@@ -806,7 +806,7 @@ mixin SchedulerBinding on BindingBase {
   /// schedules a frame, set [debugPrintScheduleFrameStacks] to true.
   ///
   /// Prefer using [scheduleFrame] unless it is imperative that a frame be
-  /// scheduled immediately, since using [scheduleForceFrame] will cause
+  /// scheduled immediately, since using [scheduleForcedFrame] will cause
   /// significantly higher battery usage when the device should be idle.
   ///
   /// Consider using [scheduleWarmUpFrame] instead if the goal is to update the

diff --git a/packages/flutter/lib/src/scheduler/ticker.dart b/packages/flutter/lib/src/scheduler/ticker.dart
@@ -105,9 +105,9 @@ class Ticker {
   /// ticking. In that case, the ticker will not call its callback, and
   /// [isTicking] will be false, but time will still be progressing.
   ///
-  /// This will return false if the [Scheduler.lifecycleState] is one that
-  /// indicates the application is not currently visible (e.g. if the device's
-  /// screen is turned off).
+  /// This will return false if the [SchedulerBinding.lifecycleState] is one
+  /// that indicates the application is not currently visible (e.g. if the
+  /// device's screen is turned off).
   bool get isTicking {
     if (_future == null)
       return false;

diff --git a/packages/flutter/lib/src/semantics/binding.dart b/packages/flutter/lib/src/semantics/binding.dart
@@ -50,7 +50,8 @@ mixin SemanticsBinding on BindingBase {
   /// a flag is changed.
   ///
   /// To listen to changes to accessibility features, create a
-  /// [WidgetsBindingObserver] and listen to [didChangeAccessibilityFeatures].
+  /// [WidgetsBindingObserver] and listen to
+  /// [WidgetsBindingObserver.didChangeAccessibilityFeatures].
   ui.AccessibilityFeatures get accessibilityFeatures => _accessibilityFeatures;
   ui.AccessibilityFeatures _accessibilityFeatures;