Improve doc comments

CHANGELOG.md

@@ -1,8 +1,9 @@
 ## 1.0.0-beta.6
 
 - Rename `fullPath` property to `fullPathTemplate`
-- Add `populatedWith` method to `DataRoute`
+- Rename `generate` to `populatedWith`
 - Add `joinSegments` method to base class and remove `toPath` extension method
+- Add and improve doc comments
 
 ## 1.0.0-beta.5
 

lib/src/extensions/enum_extensions.dart

@@ -1,4 +1,5 @@
 extension EnumExtensions on Enum {
  /// Get the path template parameter name for this enum value.
+ /// e.g. `RouteParams.id.prefixed` returns `:id`
  String get prefixed => ':$name';
 }

lib/src/route_data.dart

@@ -1,12 +1,75 @@
+/// A class that contains data to be injected into a route.
+/// This can be path parameters, query parameters, or "extra" data, or any
+/// combination of the three.
 abstract class SimpleRouteData {
  const SimpleRouteData();
 
- /// Inject path parameters into the route.
+ /// Path parameters to be injected into the route.
+ ///
+ /// ```dart
+ /// class MyRouteData extends SimpleRouteData {
+ /// const MyRouteData(this.userId);
+ ///
+ /// final String userId;
+ ///
+ /// @override
+ /// Map<Enum, String> get parameters => {
+ /// // The `userId` value will be injected into the path,
+ /// // replacing the `:userId` template parameter.
+ /// RouteParams.userId: userId,
+ /// };
+ /// }
+ /// ```
  Map<Enum, String> get parameters => const {};
 
- /// Inject "extra" data into the route.
+ /// Inject "extra" data into the [GoRouterState].
+ ///
+ /// ```dart
+ /// class MyRouteData extends SimpleRouteData {
+ /// const MyRouteData(this.extra);
+ ///
+ /// final MyExtraDataClass extra;
+ ///
+ /// @override
+ /// MyExtraDataClass get extra => extra;
+ /// }
+ /// ```
+ ///
+ /// This data will be stored on `GoRouterState.extra` and can be accessed
+ /// directly or by using the `getExtra<T>()` extension method.
+ ///
+ /// ```dart
+ /// final extra = context.getExtra<MyExtraDataClass>();
+ /// ```
  Object? get extra => null;
 
- /// Inject query parameters into the route.
+ /// Query parameters to be appended to the route.
+ ///
+ /// ```dart
+ /// class MyRouteData extends SimpleRouteData {
+ /// const MyRouteData(this.redirect);
+ ///
+ /// final String? redirect;
+ ///
+ /// @override
+ /// Map<Enum, String?> get query => {
+ /// // The value of `redirect`, if not null, will be
+ /// // appended to the route as a URI-encoded query
+ /// // parameter, using the `redirect` key.
+ /// // e.g. `?redirect=/home`
+ /// QueryParams.redirect: redirect,
+ /// };
+ /// }
+ /// ```
+ ///
+ /// If the value is null or empty, the query parameter will not be appended.
+ ///
+ /// These values can be accessed directly on the
+ /// `GoRouterState.uri.queryParameters` map or by using the
+ /// `getQuery()` extension method.
+ ///
+ /// ```dart
+ /// final redirect = context.getQuery(QueryParams.redirect);
+ /// ```
  Map<Enum, String?> get query => const {};
 }

lib/src/routes.dart

@@ -31,7 +31,7 @@ abstract class BaseRoute {
 
  /// Get the full path template for this route, including any parent routes.
  ///
- /// e.g. `/auth/register/verify-email/:token`
+ /// e.g. `/user/:userId/posts/:postId`
  String get fullPathTemplate {
  var path = this is ChildRoute
  ? joinSegments([
@@ -47,7 +47,7 @@ abstract class BaseRoute {
  return path;
  }
 
- /// Get the [GoRoute] path for this route.
+ /// Get the [GoRoute] `path` for this route.
  ///
  /// ```dart
  /// GoRoute(
@@ -91,6 +91,17 @@ abstract class BaseRoute {
 }
 
 /// A route that contains no parameters.
+///
+/// Override the `path` getter to declare the path segment for this route.
+///
+/// ```dart
+/// class MyRoute extends SimpleRoute {
+/// const MyRoute();
+///
+/// @override
+/// String get path => 'my-route';
+/// }
+/// ```
 abstract class SimpleRoute extends BaseRoute {
  const SimpleRoute();
 
@@ -105,8 +116,22 @@ abstract class SimpleRoute extends BaseRoute {
  }
 }
 
-/// A route that contains a parameter. When navigating, data must be supplied
-/// to populate the route.
+/// A route that contains one or more path and/or query parameters and/or
+/// "extra" data.
+///
+/// When navigating, a data object must be supplied to populate the route.
+///
+/// In this example, the `MyRouteData` class should provide a value for the
+/// `:id` path parameter (declared by the `RouteParams.id` enum value).
+///
+/// ```dart
+/// class MyRoute extends DataRoute<MyRouteData> {
+/// const MyRoute();
+///
+/// @override
+/// String get path => joinSegments(['my-route', RouteParams.id.prefixed]);
+/// }
+/// ```
 abstract class DataRoute<Data extends SimpleRouteData> extends BaseRoute {
  const DataRoute();
 
@@ -126,7 +151,12 @@ abstract class DataRoute<Data extends SimpleRouteData> extends BaseRoute {
  GoRouter.of(context).push(populatedWith(data), extra: data.extra);
  }
 
- /// Generate a populated path for this route using the supplied [data].
+ /// Generate the populated path for this route using the supplied [data].
+ ///
+ /// This method will inject the [data] parameters into the path template and
+ /// append any query parameters.
+ ///
+ /// e.g. `/user/:userId` becomes `/user/123?query=my%20query`
  String populatedWith(Data data) {
  return _injectParams(fullPathTemplate, data).appendQuery(_getQuery(data));
  }
@@ -148,6 +178,31 @@ abstract class DataRoute<Data extends SimpleRouteData> extends BaseRoute {
  }
 }
 
+/// A route that is a descendant of another route.
+///
+/// Implement this interface to declare a route as a child of another route
+/// in the routing tree.
+///
+/// ```dart
+/// class MyRoute extends SimpleRoute implements ChildRoute<ParentRoute> {
+/// const MyRoute();
+///
+/// @override
+/// String get path => 'my-route';
+///
+/// @override
+/// ParentRoute get parent => const ParentRoute();
+/// }
+/// ```
+///
+/// Then, when navigating to this route, it will automatically construct the
+/// full path using the parent route's path.
+///
+/// ```dart
+/// const MyRoute().go(context);
+/// ```
+///
+/// This will navigate to '/parent-route/my-route'.
 abstract class ChildRoute<Parent extends BaseRoute> {
  /// The parent route of this route.
  Parent get parent;