diff --git a/packages/go_router/CHANGELOG.md b/packages/go_router/CHANGELOG.md index 170609a6482..b928c46d5af 100644 --- a/packages/go_router/CHANGELOG.md +++ b/packages/go_router/CHANGELOG.md @@ -3,6 +3,7 @@ - Aligns Dart and Flutter SDK constraints. - Updates compileSdkVersion to 33. - Updates example app to iOS 11. +- Updates documentation in matching methods. ## 6.2.0 diff --git a/packages/go_router/lib/src/matching.dart b/packages/go_router/lib/src/matching.dart index 86e570210f6..b67c69bcd2c 100644 --- a/packages/go_router/lib/src/matching.dart +++ b/packages/go_router/lib/src/matching.dart @@ -48,6 +48,8 @@ class RouteMatcher { } /// The list of [RouteMatch] objects. +/// +/// This corresponds to the GoRouter's history. class RouteMatchList { /// RouteMatchList constructor. RouteMatchList(List matches, this._uri, this.pathParameters) @@ -58,6 +60,33 @@ class RouteMatchList { static RouteMatchList empty = RouteMatchList([], Uri.parse(''), const {}); + /// Generates the full path (ex: `'/family/:fid/person/:pid'`) of a list of + /// [RouteMatch]. + /// + /// This methods considers that [matches]'s elements verify the go route + /// structure given to `GoRouter`. For example, if the routes structure is + /// + /// ```dart + /// GoRoute( + /// path: '/a', + /// routes: [ + /// GoRoute( + /// path: 'b', + /// routes: [ + /// GoRoute( + /// path: 'c', + /// ), + /// ], + /// ), + /// ], + /// ), + /// ``` + /// + /// The [matches] must be the in same order of how GoRoutes are matched. + /// + /// ```dart + /// [RouteMatchA(), RouteMatchB(), RouteMatchC()] + /// ``` static String _generateFullPath(Iterable matches) { final StringBuffer buffer = StringBuffer(); bool addsSlash = false; @@ -77,7 +106,12 @@ class RouteMatchList { final List _matches; /// the full path pattern that matches the uri. - /// /family/:fid/person/:pid + /// + /// For example: + /// + /// ```dart + /// '/family/:fid/person/:pid' + /// ``` final String fullpath; /// Parameters for the matched route, URI-encoded. @@ -159,6 +193,18 @@ class MatcherError extends Error { } } +/// Returns the list of `RouteMatch` corresponding to the given `loc`. +/// +/// For example, for a given `loc` `/a/b/c/d`, this function will return the +/// list of [RouteBase] `[GoRouteA(), GoRouterB(), GoRouteC(), GoRouterD()]`. +/// +/// - [loc] is the complete URL to match (without the query parameters). For +/// example, for the URL `/a/b?c=0`, [loc] will be `/a/b`. +/// - [restLoc] is the remaining part of the URL to match while [parentSubloc] +/// is the part of the URL that has already been matched. For examples, for +/// the URL `/a/b/c/d`, at some point, [restLoc] would be `/c/d` and +/// [parentSubloc] will be `/a/b`. +/// - [routes] are the possible [RouteBase] to match to [restLoc]. List? _getLocRouteRecursively({ required String loc, required String restLoc,