anchor.diff:  
     final List<ProviderStateOwnerObserver> _observers;
     final VoidCallback _markNeedsUpdate;
  -  List<ProviderOverride> _debugOverrides;
  +
  +  /// The currently overriden providers.
  +  ///
  +  /// New keys cannot be added after creation, unless this [ProviderStateOwner]
  +  /// does not have a `parent`.
  +  /// Upating existing keys is possible.
     final _overrideForProvider = <ProviderBase, ProviderBase>{};
  +
  +  /// The list of all provider states sorted by how deep they are in the graph
  +  /// of dependencies.
  +  ///
  +  /// It exists for [update] and [dispose] to efficiently traverse all providers
  +  /// in order of dependency with a O(N) complexity.
     final _providerStatesSortedByDepth =
         LinkedList<_LinkedListEntry<ProviderStateBase>>();
  +
  +  /// The state of all providers. Reading a provider is O(1).
     Map<ProviderBase, _ProviderStateReader> _stateReaders;
  +
  +  /// When attempting to read a provider, a provider may not be registered
  +  /// inside [_stateReaders] with a [_ProviderStateReader].
  +  /// In that situation, [_fallback] is called and will handle register the
  +  /// provider accordingly.
  +  ///
  +  /// This is typically done only when [ProviderStateOwner] has not `parent`.
  +  _FallbackProviderStateReader _fallback;
  +
  +  /// Whether [dispose] was called or not.
  +  ///
  +  /// This disables the different methods of [ProviderStateOwner], resulting in
  +  /// a [StateError] when attempting to use them.
     bool _disposed = false;
  +
  +  /// A snapshot of the current overrides, used by [update] to ensure that
  +  /// updating the list of overrides is done correctly.
  +  List<ProviderOverride> _debugOverrides;
   
     /// The state of `Computed` providers
     ///
     /// It is not stored inside [_stateReaders] as `Computed` are always
     /// in the deepest [ProviderStateOwner] possible.
     Map<Computed, _ProviderStateReader> _computedStateReaders;
  -  _FallbackProviderStateReader _fallback;
     var _updateScheduled = false;
   
  -  /// All the providers that changed and their new value
  +  /// All the providers that changed and their new value.
     ///
     /// This property is an implementation detail of [ProviderStateOwnerObserver.didUpdateProviders].
  +  /// It is `null` outside of [_notifyListeners].
     Map<ProviderBase, Object> _providerChanges;
   
     // TODO: should _redepth be optimized for this use-case? As `ref` can safely always
     // be the last provider in the list of providers per depth
  +  /// An utility to easily obtain a [ProviderReference] from a [ProviderStateOwner].
  +  ///
  +  /// This is equivalent to:
  +  ///
  +  /// ```dart
  +  /// final refProvider = Provider((ref) => ref);
  +  /// final owner = ProviderStateOwnrr(overrides: [refProvider]);
  +  ///
  +  /// final re = refProvider.readOwner(owner);
  +  /// ```
     ProviderReference get ref => _refProvider.readOwner(this);
   
  -  Map<ProviderBase, Object> get debugProviderStates {
  -    Map<ProviderBase, Object> res;
  -    assert(() {
  -      res = {
  -        for (final entry in _stateReaders.entries)
  -          if (entry.value._providerState != null)
  -            entry.key: entry.value._providerState.state,
  -      };
  -
  -      return true;
  -    }(), '');
  -    return res;
  -  }
  -
  +  /// Notify listeners about changes associated to a provider, and optionally
  +  /// allow changing the list of provider overrides.
  +  ///
  +  /// The providers will dispatch their notifications in order
  +  /// based on if they depend on other providers or not:
  +  ///
  +  /// - A provider with no dependency on other providers will notify its
  +  ///   listeners first.
  +  /// - A provider that depends on all the other providers of the application
  +  ///   will notify its listeners last.
  +  ///
  +  ///
  +  /// Updating the list of overrides is possible, but [overrides] cannot
  +  /// remove or add new overrides.
  +  /// What this means is, if [ProviderStateOwner] was created with 3 overrides,
  +  /// calls to [update] that tries to change the list of overrides must override
  +  /// these 3 exact providers again.
  +  ///
  +  /// As an example, consider:
  +  ///
  +  /// ```dart
  +  /// final provider1 = FutureProvider((_) async => 'Hello');
  +  /// final provider2 = Provider((_) => 'world');
  +  ///
  +  /// final owner = ProviderStateOwner(
  +  ///   overrides: [
  +  ///     provider1.debugOverrideWithValue(const AsyncValue.loading())
  +  ///     provider2.overrideForSubtree(Provider((_) => 'London')),
  +  ///   ],
  +  /// );
  +  /// ```
  +  ///
  +  /// Then we can call update with different overrides:
  +  ///
  +  /// ```dart
  +  /// owner.update([
  +  ///   provider1.debugOverrideWithValue(const AsyncValue.data('Hi'))
  +  ///   provider2.overrideForSubtree(Provider((_) => 'London')),
  +  /// ]);
  +  /// ```
  +  ///
  +  /// But we cannot call [update] with different overrides:
  +  ///
  +  /// ```dart
  +  /// // Invalid, provider2 was overiden before but is not anymore
  +  /// owner.update([
  +  ///   provider1.debugOverrideWithValue(const AsyncValue.data('Hi'))
  +  /// ]);
  +  ///
  +  /// // Invalid, provider3 was not overriden before, but now is
  +  /// owner.update([
  +  ///   provider1.debugOverrideWithValue(const AsyncValue.data('Hi'))
  +  ///   provider2.overrideForSubtree(Provider((_) => 'London')),
  +  ///   provider3.overrideForSubtree(...),
  +  /// ]);
  +  /// ```
     void update([List<ProviderOverride> overrides]) {
       if (_disposed) {
         throw StateError(
  
positive.code:           override._origin is! Computed && override._provider is! Computed,
            'Cannot override Computed',
          );
          // no need to check _computedStateReaders as they are not overridable
          final state = _stateReaders[override._origin]
              // _providerState instead of read() to not compute the state
              ._providerState;
          if (state == null) {
            continue;
  
negative.code:     _updateScheduled = false;
    }
  
    /// Used by [ProviderStateBase.notifyListeners] to let [ProviderStateOwner]
    /// know that a provider _truly_ changed.
    ///
    /// This is then used to notify [ProviderStateOwnerObserver]s of the changes.
    void _reportChanged(ProviderBase origin, Object state) {
      if (_observers != null && _observers.isNotEmpty) {
        _providerChanges ??= {};
  