[go_router] Add documentation to some methods in matching.dart

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
 

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<RouteMatch> matches, this._uri, this.pathParameters)
@@ -58,6 +60,11 @@ class RouteMatchList {
   static RouteMatchList empty =
       RouteMatchList(<RouteMatch>[], Uri.parse(''), const <String, String>{});
 
+  /// 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<RouteMatch> matches) {
     final StringBuffer buffer = StringBuffer();
     bool addsSlash = false;
@@ -76,8 +83,11 @@ class RouteMatchList {
 
   final List<RouteMatch> _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<RouteMatch>? _getLocRouteRecursively({
   required String loc,
   required String restLoc,