From 204bd9e9b1877e588140f9679afd792108d2d054 Mon Sep 17 00:00:00 2001 From: ValentinVignal Date: Wed, 15 Mar 2023 15:49:17 +0800 Subject: [PATCH 1/4] docs: Add documentation --- packages/go_router/lib/src/matching.dart | 25 ++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/packages/go_router/lib/src/matching.dart b/packages/go_router/lib/src/matching.dart index 86e570210f6..a71b5232824 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,11 @@ class RouteMatchList { static RouteMatchList empty = RouteMatchList([], Uri.parse(''), const {}); + /// Generate the full path (ex: `'/family/:fid/person/:pid'`) of a list of + /// [RouteMatch]. + /// + /// This methods considers that [matches] is ordered accorresponding to how + /// the routes are given to `GoRouter`. static String _generateFullPath(Iterable matches) { final StringBuffer buffer = StringBuffer(); bool addsSlash = false; @@ -76,8 +83,11 @@ class RouteMatchList { final List _matches; - /// the full path pattern that matches the uri. - /// /family/:fid/person/:pid + /// the full path pattern that matches the uri. For example: + /// + /// ```dart + /// '/family/:fid/person/:pid' + /// ``` final String fullpath; /// Parameters for the matched route, URI-encoded. @@ -159,6 +169,17 @@ 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`. +/// - [restBloc] is the remaining part of the URL to match while [parentBloc] is +/// the part of the URL that has already been matched. For examples, for the +/// URL `/a/b/c/d`, at some point, [restBloc] would be `/c/d` and [parentBloc] +/// will be `/a/b`. +/// - [routes] are the possible [RouteBase] to match to [restBloc]. List? _getLocRouteRecursively({ required String loc, required String restLoc, From 5e4338a63715e775571c6845222821128296c2a6 Mon Sep 17 00:00:00 2001 From: ValentinVignal Date: Wed, 15 Mar 2023 15:55:53 +0800 Subject: [PATCH 2/4] docs: Update changelogs --- packages/go_router/CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) 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 From f12243ac360b25394893e7e0b4cbf5352ebd45be Mon Sep 17 00:00:00 2001 From: ValentinVignal Date: Thu, 16 Mar 2023 09:25:41 +0800 Subject: [PATCH 3/4] docs: Better documentation --- packages/go_router/lib/src/matching.dart | 48 ++++++++++++++++++------ 1 file changed, 37 insertions(+), 11 deletions(-) diff --git a/packages/go_router/lib/src/matching.dart b/packages/go_router/lib/src/matching.dart index a71b5232824..008892c8554 100644 --- a/packages/go_router/lib/src/matching.dart +++ b/packages/go_router/lib/src/matching.dart @@ -63,8 +63,31 @@ class RouteMatchList { /// Generate the full path (ex: `'/family/:fid/person/:pid'`) of a list of /// [RouteMatch]. /// - /// This methods considers that [matches] is ordered accorresponding to how - /// the routes are given to `GoRouter`. + /// 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', + /// ), + /// ], + /// ), + /// ], + /// ), + /// ``` + /// + /// [matches] will be a list of [RouteMatch] corresponding to the routes: + /// + /// ```dart + /// [RouteMatchA(), RouteMatchB(), RouteMatchC()] + /// ``` static String _generateFullPath(Iterable matches) { final StringBuffer buffer = StringBuffer(); bool addsSlash = false; @@ -83,7 +106,9 @@ class RouteMatchList { final List _matches; - /// the full path pattern that matches the uri. For example: + /// the full path pattern that matches the uri. + /// + /// For example: /// /// ```dart /// '/family/:fid/person/:pid' @@ -169,17 +194,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()]`. +/// 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`. -/// - [restBloc] is the remaining part of the URL to match while [parentBloc] is -/// the part of the URL that has already been matched. For examples, for the -/// URL `/a/b/c/d`, at some point, [restBloc] would be `/c/d` and [parentBloc] -/// will be `/a/b`. -/// - [routes] are the possible [RouteBase] to match to [restBloc]. +/// - [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, From 1034adf302d6fc4ed18b7d557e9fe1b9320e4287 Mon Sep 17 00:00:00 2001 From: ValentinVignal Date: Fri, 17 Mar 2023 09:15:36 +0800 Subject: [PATCH 4/4] docs: Better documentation and fix typos --- packages/go_router/lib/src/matching.dart | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/packages/go_router/lib/src/matching.dart b/packages/go_router/lib/src/matching.dart index 008892c8554..b67c69bcd2c 100644 --- a/packages/go_router/lib/src/matching.dart +++ b/packages/go_router/lib/src/matching.dart @@ -60,12 +60,11 @@ class RouteMatchList { static RouteMatchList empty = RouteMatchList([], Uri.parse(''), const {}); - /// Generate the full path (ex: `'/family/:fid/person/:pid'`) of a list of + /// 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 + /// structure given to `GoRouter`. For example, if the routes structure is /// /// ```dart /// GoRoute( @@ -83,7 +82,7 @@ class RouteMatchList { /// ), /// ``` /// - /// [matches] will be a list of [RouteMatch] corresponding to the routes: + /// The [matches] must be the in same order of how GoRoutes are matched. /// /// ```dart /// [RouteMatchA(), RouteMatchB(), RouteMatchC()] @@ -194,9 +193,9 @@ class MatcherError extends Error { } } -/// Returns the list of `RouteMatch` corresponding to the given [loc]. +/// 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 +/// 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