From f3dec248e509cadb29716e91792c70f413b93c51 Mon Sep 17 00:00:00 2001
From: Tom Gilder <tom.gilder@codemate.com>
Date: Sun, 13 Mar 2022 14:08:55 +0200
Subject: [PATCH] Update push and replace docs (#263)

Fixes #224
---
 lib/routemaster.dart | 73 ++++++++++++++++++++++++++------------------
 1 file changed, 43 insertions(+), 30 deletions(-)

diff --git a/lib/routemaster.dart b/lib/routemaster.dart
index dbd3046..abea879 100644
--- a/lib/routemaster.dart
+++ b/lib/routemaster.dart
@@ -170,21 +170,14 @@ class Routemaster {
     return _state.delegate.popUntil(predicate);
   }
 
-  /// Replaces the current route with [path].
-  ///
-  /// If the given [path] starts with a forward slash, it's treated as an
-  /// absolute path.
-  ///
-  /// If it doesn't start with a forward slash, it's treated as a relative path
-  /// to the current route.
-  ///
-  /// For example:
+  /// Replaces the current route with [path]. On the web, this prevents the user
+  /// returning to the previous route via the back button.
   ///
-  ///   * If the current route is '/products' and you call `replace('1')`
-  ///     you'll navigate to '/products/1'.
+  ///   * [path] - an absolute or relative path. See [push] for the difference
+  ///     between the two.
   ///
-  ///   * If the current route is '/products' and you call `replace('/home')`
-  ///     you'll navigate to '/home'.
+  ///   * [queryParameters] - an optional map of string parameters to be passed
+  ///     to the new route.
   ///
   void replace(String path, {Map<String, String>? queryParameters}) {
     final routeData = RouteData.maybeOf(_context);
@@ -205,21 +198,26 @@ class Routemaster {
     _state.delegate.replace(path, queryParameters: queryParameters);
   }
 
-  /// Pushes [path] into the navigation tree.
+  /// Navigates to [path].
+  ///
+  /// If this path starts with a forward slash, it's treated as an absolute
+  /// path. Otherwise it's handled as a path relative to the current route.
+  ///
+  /// For example, if the current route is '/products':
   ///
-  /// If the given [path] starts with a forward slash, it's treated as an
-  /// absolute path.
+  ///   * Calling `push('1')` navigates to '/products/1'.
   ///
-  /// If it doesn't start with a forward slash, it's treated as a relative path
-  /// to the current route.
+  ///   * Calling `push('/home')` navigates to '/home'.
   ///
-  /// For example:
+  /// A [queryParameters] map can be added to pass string parameters to the new
+  /// route:
   ///
-  ///   * If the current route is '/products' and you call `replace('1')`
-  ///     you'll navigate to '/products/1'.
+  ///   `push('/search', queryParameters: {'query': 'hello'})`
   ///
-  ///   * If the current route is '/products' and you call `replace('/home')`
-  ///     you'll navigate to '/home'.
+  /// These can then be access from [RouteData], using
+  /// `RouteData.of(context).queryParameters`, or from within a route map:
+  ///
+  ///   `'/product': (route) => MaterialPage(child: SearchPage(route.queryParameters['id']))`
   ///
   @optionalTypeArgs
   NavigationResult<T> push<T extends Object?>(
@@ -400,12 +398,26 @@ class RoutemasterDelegate extends RouterDelegate<RouteData>
     }
   }
 
-  /// Pushes [path] into the navigation tree.
+  /// Navigates to [path].
+  ///
+  /// If this path starts with a forward slash, it's treated as an absolute
+  /// path. Otherwise it's handled as a path relative to the current route.
+  ///
+  /// For example, if the current route is '/products':
+  ///
+  ///   * Calling `push('1')` navigates to '/products/1'.
+  ///
+  ///   * Calling `push('/home')` navigates to '/home'.
+  ///
+  /// A [queryParameters] map can be added to pass string parameters to the new
+  /// route:
+  ///
+  ///   `push('/search', queryParameters: {'query': 'hello'})`
   ///
-  ///   * [path] - an absolute or relative path.
+  /// These can then be access from [RouteData], using
+  /// `RouteData.of(context).queryParameters`, or from within a route map:
   ///
-  ///   * [queryParameters] - an optional map of parameters to be passed to the
-  ///     created page.
+  ///   `'/product': (route) => MaterialPage(child: SearchPage(route.queryParameters['id']))`
   ///
   @optionalTypeArgs
   NavigationResult<T> push<T extends Object?>(
@@ -443,10 +455,11 @@ class RoutemasterDelegate extends RouterDelegate<RouteData>
   /// Replaces the current route with [path]. On the web, this prevents the user
   /// returning to the previous route via the back button.
   ///
-  ///   * [path] - an absolute or relative path.
+  ///   * [path] - an absolute or relative path. See [push] for the difference
+  ///     between the two.
   ///
-  ///   * [queryParameters] - an optional map of parameters to be passed to the
-  ///     created page.
+  ///   * [queryParameters] - an optional map of string parameters to be passed
+  ///     to the new route.
   ///
   void replace(String path, {Map<String, String>? queryParameters}) {
     assert(!_isDisposed);