Expanding the documentation#463
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughDocumentation in Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
| /// [Hook] is similar to a [StatelessWidget], but is not associated | ||
| /// to an [Element]. | ||
| /// Allows a [Widget] to create and access its own mutable data | ||
| /// without implementing a [State]. |
There was a problem hiding this comment.
I thought that "not associated to an Element" might lead to confusion, because much like a StatefulWidget, Hook has a createState() method, and the object returned has access to the context.
| /// A [Hook] is typically the equivalent of [State] for [StatefulWidget], | ||
| /// with the notable difference that a [HookWidget] can have more than one [Hook]. | ||
| /// A [Hook] is created within the [HookState.build] method of a [HookWidget] and the creation | ||
| /// must be made unconditionally, always in the same order. | ||
| /// Whereas [Widget]s store the immutable configuration for UI components, | ||
| /// [Hook]s store immutable configuration for any type of object. | ||
| /// The [HookState] of a [Hook] is analogous to the [State] of a [StatefulWidget], | ||
| /// and a single [HookWidget] can use more than one [Hook]. | ||
| /// | ||
| /// Hooks can be used by replacing `extends StatelessWidget` with `extends HookWidget`, | ||
| /// or by replacing `Builder()` with `HookBuilder()`. | ||
| /// | ||
| /// Hook functions must be called unconditionally during the `build()` method, | ||
| /// and always in the same order. |
There was a problem hiding this comment.
A [Hook] is typically the equivalent of [State]
This makes sense, since you can go by the philosophy of "rather than making a State, make a Hook instead".
However, in my mind, the equivalent of State would be HookState rather than Hook.
My hope is that the adjusted wording creates a good intuition while avoiding this caveat.
A [Hook] is created within the [HookState.build] method of a [HookWidget]
I believe this sentence was a typo: a HookState is created by a Hook, not the other way around.
| /// Called before a [build] triggered by [markMayNeedRebuild]. | ||
| /// | ||
| /// If [shouldRebuild] returns `false` on all the hooks that called [markMayNeedRebuild] | ||
| /// then this aborts the rebuild of the associated [HookWidget]. | ||
| /// | ||
| /// There is no guarantee that this method will be called after [markMayNeedRebuild] | ||
| /// was called. | ||
| /// Some situations where [shouldRebuild] will not be called: | ||
| /// If [shouldRebuild] returns `false` on all the hooks that called [markMayNeedRebuild], | ||
| /// [HookElement.build] will return a cached value instead of rebuilding each [Hook]. | ||
| /// | ||
| /// - [setState] was called | ||
| /// - a previous hook's [shouldRebuild] returned `true` | ||
| /// - the associated [HookWidget] changed. | ||
| /// This method is not evaluated if a previous Hook called [markMayNeedRebuild] | ||
| /// and its [shouldRebuild] method returned `true`. | ||
| /// Additionally, if [setState], [didUpdateHook], or [HookElement.didChangeDependencies] is called, | ||
| /// the build is unconditional and the `shouldRebuild()` call is skipped. | ||
| bool shouldRebuild() => true; |
There was a problem hiding this comment.
I thought the original description was really good, but I saw that (1) a rebuild will happen anyway if "a previous hook's shouldRebuild returned true" and (2) the method returns true by default… and for some reason I totally missed that only the hooks that called markMayNeedRebuild are checked.
I also saw that the 3 bullet points technically didn't cover every possibility, since an InheritedWidget could also trigger an unconditional rebuild.
| /// A [Widget] that can use a [Hook]. | ||
| /// A [Widget] that can use [Hook]s. |
There was a problem hiding this comment.
My hope was to tweak the wording here, so it's more explicit that you can use multiple Hooks.
|
Quick update—I've reverted the changes to the Hopefully now we can just focus on the uncontroversial changes here. I especially like the implementation of |
nate-thegrate
force-pushed
the
documentation
branch
from
c953b72 to
4c2f83c
Compare
2 participants
I've been doing things with Hooks a lot over the past few months, and it's been really fun to learn about the inner mechanisms of flutter_hooks.
The goal of this PR is to flesh out a few of the API descriptions and to tweak the wording in a few places for better accuracy.
Summary by CodeRabbit