Improved documentation for SpringSimulation #146674

drown0315 · 2024-04-12T07:22:18Z

Add a code snippet demonstrating the usage of SpringSimulation in the docs.
Improve the descriptions of each argument in SpringDescription.

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

justinmc

Some minor suggestions here but looks like an improvement overall. Thanks!

packages/flutter/lib/src/physics/spring_simulation.dart

justinmc · 2024-04-17T20:08:59Z

packages/flutter/lib/src/physics/spring_simulation.dart

@@ -37,16 +44,26 @@ class SpringDescription {
    double ratio = 1.0,
  }) : damping = ratio * 2.0 * math.sqrt(mass * stiffness);

+  /// The greater the mass, the larger the amplitude of oscillation,
+  /// and the slower the speed of returning to the equilibrium position.


Nit: I worry "speed" here is misleading, if I get myself back in the mindset of physics class. Maybe say "rate" instead? Or "the longer the time to return to the equilibrium position"

Thanks for your reply, your concerns are very valid. I prefer the latter

justinmc · 2024-04-17T20:09:39Z

packages/flutter/lib/src/physics/spring_simulation.dart

@@ -37,16 +44,26 @@ class SpringDescription {
    double ratio = 1.0,
  }) : damping = ratio * 2.0 * math.sqrt(mass * stiffness);

+  /// The greater the mass, the larger the amplitude of oscillation,


I feel like this paragraph belongs after the next one.

justinmc · 2024-04-17T20:09:59Z

packages/flutter/lib/src/physics/spring_simulation.dart

  /// The mass of the spring (m). The units are arbitrary, but all springs
  /// within a system should use the same mass units.
  final double mass;

+  /// Stiffness defines the spring constant, which measures the strength of


I also think that this paragraph would be better after the next paragraph.

justinmc · 2024-04-17T20:12:53Z

packages/flutter/lib/src/physics/spring_simulation.dart

+  /// The damping coefficient (c), A pure number without physical meaning,
+  /// describes the oscillation and decay of a system after being disturbed.
+  /// The larger the damping, the fewer oscillations and smaller the amplitude
+  /// of the elastic motion.


I would leave the original first sentence and keep it as its own paragraph, then make your additions a second paragraph (making sure your first sentence is a complete sentence). Something like:

The damping coefficient (c).

It is a pure number without physical meaning that describes the oscillation and decay of a system after being disturbed. The larger the damping...

Thanks, I think this might make the structure clearer. I've reorganized the parameters for mass, stiffness, and damping accordingly.

justinmc · 2024-04-17T20:13:18Z

packages/flutter/lib/src/physics/spring_simulation.dart

+/// This method triggers an [AnimationController] (a previously constructed)
+/// `_controller` field) to simulate a spring oscillation.


You have mismatched parentheses here.

justinmc · 2024-04-17T20:13:56Z

packages/flutter/lib/src/physics/spring_simulation.dart

+/// {@end-tool}
+/// This [AnimationController] could be used with an [AnimatedBuilder] to


Nit: There should be an empty row of /// between these two lines I think.

drown0315 · 2024-04-19T03:18:07Z

@justinmc Thanks for review, I've already made overall updates.

justinmc

LGTM with nits. Thanks for the fixes here and for improving our docs!

justinmc · 2024-05-01T23:25:51Z

packages/flutter/lib/src/physics/spring_simulation.dart

+  /// the spring. A stiff spring applies more force to the object that is
+  /// attached when the spring is not at the rest position.


Another physics nit. Rephrasing the last sentence here:

A stiff spring applies more force to the object that is attached for some deviation from the rest position.

justinmc · 2024-05-01T23:26:39Z

packages/flutter/lib/src/physics/spring_simulation.dart

+  /// It is a pure number without physical meaning,describes the oscillation
+  /// and decay of a system after being disturbed.The larger the damping,
+  /// the fewer oscillations and smaller the amplitude of the elastic motion.


"meaning,describes" => "meaning and describes"

Also space after the period: "disturbed. The"

justinmc · 2024-05-01T23:27:33Z

packages/flutter/lib/src/physics/spring_simulation.dart

+/// {@end-tool}
+///
+/// This [AnimationController] could be used with an [AnimatedBuilder] to
+/// animate the position of a child as if it was attached to a spring.


Super nit: "as if it was" => "as if it were"

drown0315 · 2024-05-03T03:43:25Z

@justinmc Thanks for review👍, I've already made overall updates.

auto-submit · 2024-05-03T07:05:22Z

auto label is removed for flutter/flutter/146674, due to This PR has not met approval requirements for merging. The PR author is not a member of flutter-hackers and needs 1 more review(s) in order to merge this PR.

Merge guidelines: A PR needs at least one approved review if the author is already part of flutter-hackers or two member reviews if the author is not a flutter-hacker before re-applying the autosubmit label. Reviewers: If you left a comment approving, please use the "approve" review action instead.

bleroux

LGTM!

…146674)

flutter/flutter@bf7191f...f1037a0 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from 445c3bfc0d5b to 8cce00433073 (1 revision) (flutter/flutter#147778) 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from 1f9edbeeceb3 to 445c3bfc0d5b (1 revision) (flutter/flutter#147776) 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from 75eb18090510 to 1f9edbeeceb3 (1 revision) (flutter/flutter#147769) 2024-05-03 108989782+drown0315@users.noreply.github.com Improved documentation for SpringSimulation (flutter/flutter#146674) 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from b8d81a4f6e5a to 75eb18090510 (1 revision) (flutter/flutter#147766) 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from d8c8cf4384f0 to b8d81a4f6e5a (2 revisions) (flutter/flutter#147765) 2024-05-03 gspencergoog@users.noreply.github.com Move snippets package back into flutter repo (flutter/flutter#147690) 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from 98a800b00cfc to d8c8cf4384f0 (2 revisions) (flutter/flutter#147763) 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from c380e9fd4122 to 98a800b00cfc (3 revisions) (flutter/flutter#147761) 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from fc71b650a70a to c380e9fd4122 (4 revisions) (flutter/flutter#147759) 2024-05-03 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#147741) 2024-05-03 engine-flutter-autoroll@skia.org Roll Flutter Engine from 3f1f81915620 to fc71b650a70a (2 revisions) (flutter/flutter#147753) 2024-05-02 engine-flutter-autoroll@skia.org Roll Flutter Engine from 5088f63ecee2 to 3f1f81915620 (3 revisions) (flutter/flutter#147748) 2024-05-02 yjbanov@google.com [web] skip debug mode CanvasKit e2e tests due to flakiness; unskip all other modes (flutter/flutter#147736) 2024-05-02 nate.w5687@gmail.com Control flow collections: `flutter_tools/` (flutter/flutter#147450) 2024-05-02 nate.w5687@gmail.com Add default arguments to `AnimatedPhysicalModel` (flutter/flutter#147424) 2024-05-02 engine-flutter-autoroll@skia.org Roll Flutter Engine from 9982b5ffd913 to 5088f63ecee2 (3 revisions) (flutter/flutter#147740) 2024-05-02 31859944+LongCatIsLooong@users.noreply.github.com `_RenderDecorator.computeDryBaseline` (flutter/flutter#146365) 2024-05-02 engine-flutter-autoroll@skia.org Roll Flutter Engine from e1126e59b698 to 9982b5ffd913 (1 revision) (flutter/flutter#147727) 2024-05-02 yjbanov@google.com [web] increase chromedriver logging level (flutter/flutter#147687) 2024-05-02 engine-flutter-autoroll@skia.org Roll Flutter Engine from 1fb36ac9d718 to e1126e59b698 (1 revision) (flutter/flutter#147720) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC dit@google.com,rmistry@google.com,stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

…146674)

github-actions bot added the framework flutter/packages/flutter repository. See also f: labels. label Apr 12, 2024

drown0315 force-pushed the master branch from 3c832f5 to c6a86dd Compare April 12, 2024 08:43

justinmc reviewed Apr 17, 2024

View reviewed changes

drown0315 requested a review from justinmc April 19, 2024 03:24

drown0315 force-pushed the master branch from 14d46e2 to 525cff3 Compare April 26, 2024 03:56

justinmc approved these changes May 1, 2024

View reviewed changes

drown0315 added 4 commits May 3, 2024 08:21

Improved documentation for SpringSimulation

46f186d

Fixed errors in code snippet analysis test

bfa52b3

Improved documentation for SpringSimulation

dbf0a33

Improved documentation for SpringSimulation

264ad71

bleroux force-pushed the master branch from c08fe93 to 264ad71 Compare May 3, 2024 06:21

bleroux added the autosubmit Merge PR when tree becomes green via auto submit App label May 3, 2024

auto-submit bot removed the autosubmit Merge PR when tree becomes green via auto submit App label May 3, 2024

bleroux approved these changes May 3, 2024

View reviewed changes

bleroux added the autosubmit Merge PR when tree becomes green via auto submit App label May 3, 2024

auto-submit bot merged commit cfeb76e into flutter:master May 3, 2024
73 checks passed

engine-flutter-autoroll mentioned this pull request May 3, 2024

Roll Flutter from bf7191fd3884 to f1037a01b796 (21 revisions) flutter/packages#6641

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request May 3, 2024

cfeb76e Improved documentation for SpringSimulation (flutter/flutter#…

b74a454

…146674)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 6, 2024

cfeb76e Improved documentation for SpringSimulation (flutter/flutter#…

1373b0b

…146674)

		/// This method triggers an [AnimationController] (a previously constructed)
		/// `_controller` field) to simulate a spring oscillation.

		/// {@end-tool}
		/// This [AnimationController] could be used with an [AnimatedBuilder] to

		/// the spring. A stiff spring applies more force to the object that is
		/// attached when the spring is not at the rest position.

Improved documentation for SpringSimulation #146674

Improved documentation for SpringSimulation #146674

Uh oh!

Conversation

drown0315 commented Apr 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

justinmc left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

drown0315 commented Apr 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

justinmc 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!

drown0315 commented May 3, 2024

Uh oh!

auto-submit bot commented May 3, 2024

Uh oh!

bleroux left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

drown0315 commented Apr 12, 2024 •

edited

Loading

drown0315 commented Apr 19, 2024 •

edited

Loading