Update documentation

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.0.0-beta.7
+
+- Improve migration guide
+- Improve README
+
 ## 1.0.0-beta.6
 
 - Rename `fullPath` property to `fullPathTemplate`

README.md

@@ -41,7 +41,7 @@ This package is intended to be used with the [GoRouter](https://pub.dev/packages
 ```
 dependencies:
  go_router: ^12.0.0
- simple_routes: ^1.0.0-beta.6
+ simple_routes: ^1.0.0-beta.7
 ```
 
 ## Usage
@@ -78,6 +78,8 @@ class UserProfileRoute extends SimpleRoute {
 }
 ```
 
+This method provides protection against creating a path with duplicate segments.
+
 <a id="data-routes"></a>
 
 #### Route parameters and DataRoutes
@@ -251,11 +253,12 @@ GoRouter(
  // using the `fullPathTemplate` property - this is important, 
  // as the `path` and `goPath` properties only include the 
  // route's segment(s), but not the full URI.
- //
+ return const HomeRoute().fullPathTemplate;
+
  // Note: If you're redirecting to a data route, you must use
  // the `populatedWith` method to populate the route's template
- // parameters.
- return const HomeRoute().fullPathTemplate;
+ // parameters. See the "DataRoute generation" section below.
+ // return const UserRoute().populatedWith(UserRouteData(...));
  }
 
  // If all of the data is present, return null to allow the 
@@ -320,7 +323,7 @@ redirect: (context, state) {
 }
 ```
 
-This will return the full path, with all parameters populated: `/user/123`.
+This will return the fully-populated path String: `/user/123`.
 
 ### Navigation
 

doc/migration_guide.md

@@ -6,6 +6,16 @@ This document is a guide for migrating between major package versions.
 
 This section will guide you through the breaking changes introduced in the 1.0.0 release and how to migrate your code.
 
+### Full path and populated path
+
+The `fullPath` property has been renamed to `fullPathTemplate` to better indicate its purpose. For simple routes (non-data routes), this template value is fully-populated and safe to use as a redirect or link. For data routes, however, this value will contain the _template_ parameters, such as ":userId," and should not be used as a redirect or link.
+
+To get the fully-populated path of a data route, use the new `populatedWith` method.
+
+```dart
+final link = const MyDataRoute().populatedWith(MyRouteData('user-123'));
+```
+
 ### GoRoute configuration
 
 Version 1.0.0 introduces a new `goPath` property on the `SimpleRoute` class. This property should be used when defining your `GoRoute`s instead of the `path` property.
@@ -146,7 +156,7 @@ GoRoute(
  redirect: (context, state) {
  // use the extension methods to check for the presence of data.
  if (state.getParam(RouteParams.myParam) == null) {
- return const MyOtherRoute().fullPath;
+ return const MyOtherRoute().fullPathTemplate;
  }
 
  return null;
@@ -212,18 +222,22 @@ RouteParams.myParam.prefixed,
 
 #### `join`
 
-The `join` method, which joined strings with a forward slash (/), has been replaced with the `toPath` extension method on `Iterable<String>`.
+The free-floating `join` method, which joined strings with a forward slash (`/`), has been replaced with a `joinSegments` method on the base route class.
+
+This was done to avoid leaking the method into the global namespace and to clarify its purpose and behavior.
 
 From this:
 
 ```dart
-join(['path', 'to', 'join']),
+@override
+String get path => join(['path', 'to', 'join']),
 ```
 
 To this:
 
 ```dart
-['path', 'to', 'join'].toPath(),
+@override
+String get path => joinSegments(['path', 'to', 'join']),
 ```
 
 #### `setParam`