Start fixing docs by dnfield · Pull Request #45977 · flutter/flutter

dnfield · 2019-12-03T09:10:07Z

Fixes ~200 issues currently with docs.

As it is this may have to be split up.

Addresses #31931

I basically started working from top down of dartdoc warnings/errors, although some I did en masse (e.g. DiagnosticNode -> DiagnosticsNode, SemanticNode -> SemanticsNode) and some I grabbed because they were just close by in the file.

dnfield · 2019-12-03T09:10:41Z

(There are still >600 issues remaining by local estimates)

tvolkert · 2019-12-03T16:04:23Z

packages/flutter/lib/src/animation/tween.dart


  @override
-  String toString() => '$runtimeType(value: begin)';
+  String toString() => '$runtimeType(value: $begin)';


Good catch 🙁

tvolkert · 2019-12-03T16:07:17Z

packages/flutter/lib/src/foundation/diagnostics.dart

  /// Mandatory string to add after the properties of a node regardless of
  /// whether the node has any properties.
-  ///
-  /// See [headerLineTextConfiguration] for an example of using this field to


singleLineTextConfiguration?

That field sets this to '' - doesn't seem like a great example :\

tvolkert · 2019-12-03T16:08:19Z

packages/flutter/lib/src/foundation/platform.dart

 /// Widgets and render objects at lower layers that try to emulate the
 /// underlying platform can depend on [defaultTargetPlatform] directly. The
-/// [dart.io.Platform] object should only be used directly when it's critical to
+/// [platform.Platform] object should only be used directly when it's critical to


Not [dart:io.Platform]?

packages/flutter/lib/src/gestures/events.dart

tvolkert · 2019-12-03T16:10:24Z

packages/flutter/lib/src/gestures/events.dart

  ///
  /// We occasionally synthesize PointerEvents that aren't exact translations
-  /// of [ui.PointerData] from the engine to cover small cross-OS discrepancies
+  /// of [PointerData] from the engine to cover small cross-OS discrepancies


Does this not have to be [dart:ui.PointerData]?

I think either one would work - this works because we're importing it in this file.

tvolkert · 2019-12-03T16:13:43Z

packages/flutter/lib/src/gestures/force_press.dart

  /// This function must always return values in the range 0.0 to 1.0 given a
  /// pressure that is between the minimum and maximum pressures. It may return
-  /// [double.NaN] for values that it does not want to support.
+  /// `double.NaN` for values that it does not want to support.


I wonder if it'd link it this was [dart:core.double.NaN]?

No luck. I think this is probably a dartdoc bug but I'm also not sure how important it is we link to double.NaN here.

tvolkert · 2019-12-03T16:15:45Z

packages/flutter/lib/src/material/bottom_app_bar.dart

 ///
 /// See also:
 ///
-///  * [ComputeNotch] a function used for creating a notch in a shape.


Maybe link to [NotchedShape]?

jacob314

for the widget_inspector typo fixes.

tvolkert · 2019-12-03T16:18:27Z

packages/flutter/lib/src/widgets/app.dart

  ///  1. [localeListResolutionCallback] is attempted first.
  ///  2. [localeResolutionCallback] is attempted second.
-  ///  3. Flutter's [WidgetsApp.basicLocaleListResolution] algorithm is attempted last.
+  ///  3. Flutter's basic resolution algorithm is attempted last.


Where is the basic resolution algorithm documented?

Looks like it's documented in supportedLocales - maybe link to there?

tvolkert · 2019-12-03T16:19:33Z

packages/flutter/lib/src/widgets/app.dart

  ///
  /// The order of the list matters. The default locale resolution algorithm,
-  /// [basicLocaleListResolution], attempts to match by the following priority:
+  /// `basicLocaleListResolution`, attempts to match by the following priority:


Is this a symbol at all now?

It's private API. Reworded.

tvolkert · 2019-12-03T16:20:00Z

packages/flutter/lib/src/widgets/app.dart

  ///  4. [Locale.languageCode] only
-  ///  6. [Locale.countryCode] only when all [preferredLocales] fail to match
-  ///  5. returns [supportedLocales.first] as a fallback
+  ///  5. [Locale.countryCode] only when all preferred locales fail to match


Just make these all 1.

HansMuller

LGTM

For the material and cupertino library changes

HansMuller · 2019-12-03T16:15:33Z

packages/flutter/lib/src/cupertino/colors.dart

  /// after it is resolved against a [BuildContext] that:
-  /// - has a [CupertinoTheme] whose [brightness] is [PlatformBrightness.light],
-  /// or a [MediaQuery] whose [MediaQueryData.platformBrightness] is [PlatformBrightness.light].
+  /// - has a [CupertinoTheme] whose [brightness] is [Brightness.light],


CC @LongCatIsLooong , looks like a systematic error

HansMuller · 2019-12-03T16:23:32Z

packages/flutter/lib/src/material/bottom_app_bar.dart

 ///
 /// See also:
 ///
-///  * [ComputeNotch] a function used for creating a notch in a shape.


Nice discard.

tvolkert

LGTM

dkwingsmt

Otherwise LGTM on gestures.

dkwingsmt · 2019-12-03T18:58:57Z

packages/flutter/lib/src/gestures/multitap.dart

  ///
  /// This triggers when the pointer stops contacting the device after the 2nd tap,
-  /// immediately after [onDoubleTapUp].
+  /// immediately after the second [GestureTapUpCallback].


Change the 2 lines to:

/// This triggers when the pointer stops contacting the device after the 2nd tap.

The onDoubleTapUp is an proposed API that was eventually removed. Thanks for spotting it out.

dkwingsmt

LGTM on gestures

fluttergithubbot · 2019-12-03T21:48:01Z

This pull request is not suitable for automatic merging in its current state.

This pull request has changes requested. Please resolve those before re-applying the label.

Start fixing docs

88946c4

dnfield requested review from HansMuller, dkwingsmt, jacob314 and tvolkert December 3, 2019 09:10

googlebot added the cla: yes label Dec 3, 2019

dnfield added the d: api docs Issues with https://api.flutter.dev/ label Dec 3, 2019

tvolkert reviewed Dec 3, 2019

View reviewed changes

packages/flutter/lib/src/gestures/events.dart Show resolved Hide resolved

tvolkert reviewed Dec 3, 2019

View reviewed changes

jacob314 reviewed Dec 3, 2019

View reviewed changes

tvolkert reviewed Dec 3, 2019

View reviewed changes

HansMuller approved these changes Dec 3, 2019

View reviewed changes

review

7862a77

tvolkert approved these changes Dec 3, 2019

View reviewed changes

dkwingsmt approved these changes Dec 3, 2019

View reviewed changes

dkwingsmt requested changes Dec 3, 2019

View reviewed changes

review

a38f0b1

dkwingsmt approved these changes Dec 3, 2019

View reviewed changes

dnfield added the waiting for tree to go green label Dec 3, 2019

fluttergithubbot removed the waiting for tree to go green label Dec 3, 2019

dnfield merged commit b61dec7 into flutter:master Dec 3, 2019

dnfield deleted the doc_fixup branch December 3, 2019 21:59

dnfield mentioned this pull request Dec 5, 2019

[cocoon] check-waiting-pull-requests sometimes thinks there are changes requested when there are not #46131

Closed

github-actions bot locked as resolved and limited conversation to collaborators Aug 2, 2021

Conversation

dnfield commented Dec 3, 2019

Uh oh!

dnfield commented Dec 3, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacob314 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HansMuller left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tvolkert left a comment

Choose a reason for hiding this comment

Uh oh!

dkwingsmt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkwingsmt left a comment

Choose a reason for hiding this comment

Uh oh!

fluttergithubbot commented Dec 3, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

HansMuller left a comment •

edited

Loading