Merge pull request #375 from Nipodemos/code_docs

[docs] Documenting main methods

Merge pull request #375 from Nipodemos/code_docs
[docs] Documenting main methods
Jonny Borges · GitHub
Commit 5c6f40194b417a8da8e1e3c6f2c41a7491fec50c 5c6f4019 2 parents b8aa662c 57e671b4
Showing 2 changed files with 282 additions and 89 deletions
lib/src/context_extensions/extensions.dart
lib/src/get_main.dart
--- a/lib/src/context_extensions/extensions.dart
View file @5c6f401
+++ b/lib/src/context_extensions/extensions.dart
View file @5c6f401
 import 'package:flutter/widgets.dart';
 extension MDQ on BuildContext {
+  /// The same of [MediaQuery.of(context).size]
   Size get mediaQuerySize => MediaQuery.of(this).size;
+  /// The same of [MediaQuery.of(context).size.height]
+  /// Note: updates when you rezise your screen (like on a browser or desktop window)
   double get height => mediaQuerySize.height;
+  /// The same of [MediaQuery.of(context).size.width]
+  /// Note: updates when you rezise your screen (like on a browser or desktop window)
   double get width => mediaQuerySize.width;
+  /// Gives you the power to get a portion of the height.
+  /// Useful for responsive applications.
+  ///
+  /// [dividedBy] is for when you want to have a portion of the value you would get
+  /// like for example: if you want a value that represents a third of the screen
+  /// you can set it to 3, and you will get a third of the height
+  ///
+  /// [reducedBy] is a percentage value of how much of the height you want
+  /// if you for example want 46% of the height, then you reduce it by 56%.
   double heightTransformer({double dividedBy = 1, double reducedBy = 0.0}) {
     return (mediaQuerySize.height -
             ((mediaQuerySize.height / 100) * reducedBy)) /
         dividedBy;
   }
+  /// Gives you the power to get a portion of the width.
+  /// Useful for responsive applications.
+  ///
+  /// [dividedBy] is for when you want to have a portion of the value you would get
+  /// like for example: if you want a value that represents a third of the screen
+  /// you can set it to 3, and you will get a third of the width
+  ///
+  /// [reducedBy] is a percentage value of how much of the width you want
+  /// if you for example want 46% of the width, then you reduce it by 56%.
   double widthTransformer({double dividedBy = 1, double reducedBy = 0.0}) {
     return (mediaQuerySize.width - ((mediaQuerySize.width / 100) * reducedBy)) /
         dividedBy;
   }
-  double ratio(
-      {double dividedBy = 1,
-      double reducedByW = 0.0,
-      double reducedByH = 0.0}) {
+  /// TODO: make docs about that
+  double ratio({
+    double dividedBy = 1,
+    double reducedByW = 0.0,
+    double reducedByH = 0.0,
+  }) {
     return heightTransformer(dividedBy: dividedBy, reducedBy: reducedByH) /
         widthTransformer(dividedBy: dividedBy, reducedBy: reducedByW);
   }
-  /// similar to MediaQuery.of(this).padding
+  /// similar to [MediaQuery.of(context).padding]
   EdgeInsets get mediaQueryPadding => MediaQuery.of(this).padding;
-  /// similar to MediaQuery.of(this).viewPadding
+  /// similar to [MediaQuery.of(context).viewPadding]
   EdgeInsets get mediaQueryViewPadding => MediaQuery.of(this).viewPadding;
-  /// similar to MediaQuery.of(this).viewInsets;
+  /// similar to [MediaQuery.of(context).viewInsets]
   EdgeInsets get mediaQueryViewInsets => MediaQuery.of(this).viewInsets;
-  /// similar to MediaQuery.of(this).orientation;
+  /// similar to [MediaQuery.of(context).orientation]
   Orientation get orientation => MediaQuery.of(this).orientation;
   /// check if device is on landscape mode
@@ -44,10 +69,10 @@ extension MDQ on BuildContext {
   /// check if device is on portrait mode
   bool get isPortrait => orientation == Orientation.portrait;
-  /// similar to MediaQuery.of(this).devicePixelRatio;
+  /// similar to [MediaQuery.of(this).devicePixelRatio]
   double get devicePixelRatio => MediaQuery.of(this).devicePixelRatio;
-  /// similar to MediaQuery.of(this).textScaleFactor;
+  /// similar to [MediaQuery.of(this).textScaleFactor]
   double get textScaleFactor => MediaQuery.of(this).textScaleFactor;
   /// get the shortestSide from screen
--- a/lib/src/get_main.dart
View file @5c6f401
+++ b/lib/src/get_main.dart
View file @5c6f401
@@ -29,56 +29,107 @@ class GetImpl implements GetService {
   RouteSettings settings;
   String defaultSeparator = "_";
-  ///Use to instead of Navigator.push, off instead of Navigator.pushReplacement,
-  ///offAll instead of Navigator.pushAndRemoveUntil. For named routes just add "named"
-  ///after them. Example: toNamed, offNamed, and AllNamed.
-  ///To return to the previous screen, use back().
-  ///No need to pass any context to Get, just put the name of the route inside
-  ///the parentheses and the magic will occur.
-
-  /// It replaces Navigator.push, but needs no context, and it doesn't have the Navigator.push
-  /// routes rebuild bug present in Flutter. If for some strange reason you want the default behavior
-  /// of rebuilding every app after a route, use opaque = true as the parameter.
-  Future<T> to<T>(Widget page,
-      {bool opaque,
-      Transition transition,
-      Duration duration,
-      int id,
-      bool fullscreenDialog = false,
-      Object arguments,
-      Bindings binding,
-      preventDuplicates = true,
-      bool popGesture}) {
+  /// Pushes a new [page] to the stack
+  ///
+  /// It has the advantage of not needing context,
+  /// so you can call from your business logic
+  ///
+  /// You can set a custom [transition], and a transition [duration].
+  ///
+  /// You can send any type of value to the other route in the [arguments].
+  ///
+  /// Just like native routing in Flutter, you can push a route
+  /// as a [fullscreenDialog],
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// If you want the same behavior of ios that pops a route when the user drag,
+  /// you can set [popGesture] to true
+  ///
+  /// If you're using the [Bindings] api, you must define it here
+  ///
+  /// By default, GetX will prevent you from push a route that you already in,
+  /// if you want to push anyway, set [preventDuplicates] to false
+  Future<T> to<T>(
+    Widget page, {
+    bool opaque,
+    Transition transition,
+    Duration duration,
+    int id,
+    bool fullscreenDialog = false,
+    Object arguments,
+    Bindings binding,
+    preventDuplicates = true,
+    bool popGesture,
+  }) {
     if (preventDuplicates && '/${page.runtimeType}' == currentRoute) {
       return null;
     }
-    return global(id).currentState.push(GetPageRoute(
-        opaque: opaque ?? true,
-        page: () => page,
-        settings:
-            RouteSettings(name: '/${page.runtimeType}', arguments: arguments),
-        popGesture: popGesture ?? defaultPopGesture,
-        transition: transition ?? defaultTransition,
-        fullscreenDialog: fullscreenDialog,
-        binding: binding,
-        transitionDuration: duration ?? defaultDurationTransition));
-  }
-
-  /// It replaces Navigator.pushNamed, but needs no context, and it doesn't have the Navigator.pushNamed
-  /// routes rebuild bug present in Flutter. If for some strange reason you want the default behavior
-  /// of rebuilding every app after a route, use opaque = true as the parameter.
-  Future<T> toNamed<T>(String page,
-      {Object arguments, int id, preventDuplicates = true}) {
+    return global(id).currentState.push(
+          GetPageRoute(
+            opaque: opaque ?? true,
+            page: () => page,
+            settings: RouteSettings(
+              name: '/${page.runtimeType}',
+              arguments: arguments,
+            ),
+            popGesture: popGesture ?? defaultPopGesture,
+            transition: transition ?? defaultTransition,
+            fullscreenDialog: fullscreenDialog,
+            binding: binding,
+            transitionDuration: duration ?? defaultDurationTransition,
+          ),
+        );
+  }
+
+  /// Pushes a new named [page] to the stack
+  ///
+  /// It has the advantage of not needing context, so you can call
+  /// from your business logic.
+  ///
+  /// You can send any type of value to the other route in the [arguments].
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// By default, GetX will prevent you from push a route that you already in,
+  /// if you want to push anyway, set [preventDuplicates] to false
+  ///
+  /// Note: Always put a slash on the route ('/page1'), to avoid unnexpected errors
+  Future<T> toNamed<T>(
+    String page, {
+    Object arguments,
+    int id,
+    preventDuplicates = true,
+  }) {
     if (preventDuplicates && page == currentRoute) {
       return null;
     }
     return global(id).currentState.pushNamed(page, arguments: arguments);
   }
-  /// It replaces Navigator.pushReplacementNamed, but needs no context.
-  Future<T> offNamed<T>(String page,
-      {Object arguments, int id, preventDuplicates = true}) {
+  /// Pop the current named [page] in the stack and push a new one in its place
+  ///
+  /// It has the advantage of not needing context, so you can call
+  /// from your business logic.
+  ///
+  /// You can send any type of value to the other route in the [arguments].
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// By default, GetX will prevent you from push a route that you already in,
+  /// if you want to push anyway, set [preventDuplicates] to false
+  ///
+  /// Note: Always put a slash on the route ('/page1'), to avoid unnexpected errors
+  Future<T> offNamed<T>(
+    String page, {
+    Object arguments,
+    int id,
+    preventDuplicates = true,
+  }) {
     if (preventDuplicates && page == currentRoute) {
       return null;
     }
@@ -87,29 +138,72 @@ class GetImpl implements GetService {
         .pushReplacementNamed(page, arguments: arguments);
   }
-  /// It replaces Navigator.popUntil, but needs no context.
+  /// Calls pop several times in the stack until [predicate] returns true
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// [predicate] can be used like this:
+  /// `Get.until(Get.currentRoute == '/home')`so when you get to home page,
+  ///
+  /// or also like this:
+  /// `Get.until(!Get.isDialogOpen())`, to make sure the dialog is closed
   void until(RoutePredicate predicate, {int id}) {
     // if (key.currentState.mounted) // add this if appear problems on future with route navigate
     // when widget don't mounted
     return global(id).currentState.popUntil(predicate);
   }
-  /// It replaces Navigator.pushAndRemoveUntil, but needs no context.
+  /// Push the given [page], and then pop several [pages] in the stack until
+  /// [predicate] returns true
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// [predicate] can be used like this:
+  /// `Get.until(Get.currentRoute == '/home')`so when you get to home page,
+  ///
+  /// or also like this:
+  /// `Get.until(!Get.isDialogOpen())`, to make sure the dialog is closed
   Future<T> offUntil<T>(Route<T> page, RoutePredicate predicate, {int id}) {
     // if (key.currentState.mounted) // add this if appear problems on future with route navigate
     // when widget don't mounted
     return global(id).currentState.pushAndRemoveUntil(page, predicate);
   }
-  /// It replaces Navigator.pushNamedAndRemoveUntil, but needs no context.
-  Future<T> offNamedUntil<T>(String page, RoutePredicate predicate,
-      {int id, Object arguments}) {
+  /// Push the given named [page], and then pop several pages in the stack
+  /// until [predicate] returns true
+  ///
+  /// You can send any type of value to the other route in the [arguments].
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// [predicate] can be used like this:
+  /// `Get.until(Get.currentRoute == '/home')`so when you get to home page,
+  /// or also like
+  /// `Get.until(!Get.isDialogOpen())`, to make sure the dialog is closed
+  ///
+  /// Note: Always put a slash on the route ('/page1'), to avoid unnexpected errors
+  Future<T> offNamedUntil<T>(
+    String page,
+    RoutePredicate predicate, {
+    int id,
+    Object arguments,
+  }) {
     return global(id)
         .currentState
         .pushNamedAndRemoveUntil(page, predicate, arguments: arguments);
   }
-  /// It replaces Navigator.popAndPushNamed, but needs no context.
+  /// Pop the current named page and pushes a new [page] to the stack in its place
+  ///
+  /// You can send any type of value to the other route in the [arguments].
+  /// It is very similar to `offNamed()` but use a different approach
+  ///
+  /// The `offNamed()` pop a page, and goes to the next. The `offAndToNamed()` goes
+  /// to the next page, and removes the previous one. The route transition
+  /// animation is different.
   Future<T> offAndToNamed<T>(String page,
       {Object arguments, int id, dynamic result}) {
     return global(id)
@@ -117,12 +211,25 @@ class GetImpl implements GetService {
         .popAndPushNamed(page, arguments: arguments, result: result);
   }
-  /// It replaces Navigator.removeRoute, but needs no context.
+  /// Remove a specific [route] from the stack
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
   void removeRoute(Route<dynamic> route, {int id}) {
     return global(id).currentState.removeRoute(route);
   }
-  /// It replaces Navigator.pushNamedAndRemoveUntil, but needs no context.
+  /// Push a named [page] and remove all other pages from stack
+  ///
+  /// It has the advantage of not needing context, so you can
+  /// call from your business logic.
+  ///
+  /// You can send any type of value to the other route in the [arguments].
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// Note: Always put a slash on the route ('/page1'), to avoid unexpected errors
   Future<T> offAllNamed<T>(String newRouteName,
       {RoutePredicate predicate, Object arguments, int id}) {
     var route = (Route<dynamic> rota) => false;
@@ -132,18 +239,30 @@ class GetImpl implements GetService {
         arguments: arguments);
   }
+  /// Returns true if a snackbar, dialog or bottomsheet is currently showing in the screen
   bool get isOverlaysOpen =>
       (isSnackbarOpen || isDialogOpen || isBottomSheetOpen);
+  /// returns true if there is no snackbar, dialog or bottomsheet open
   bool get isOverlaysClosed =>
       (!isSnackbarOpen && !isDialogOpen && !isBottomSheetOpen);
-  /// It replaces Navigator.pop, but needs no context.
-  void back(
-      {dynamic result,
-      bool closeOverlays = false,
-      bool canPop = true,
-      int id}) {
+  /// Pop the current page, snackbar, dialog or bottomsheet in the stack
+  ///
+  /// if your set [closeOverlays] to true, Get.back() will close the currently open
+  /// snackbar/dialog/bottomsheet AND the current page
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// It has the advantage of not needing context, so you can call
+  /// from your business logic.
+  void back({
+    dynamic result,
+    bool closeOverlays = false,
+    bool canPop = true,
+    int id,
+  }) {
     if (closeOverlays && isOverlaysOpen) {
       navigator.popUntil((route) {
         return (isOverlaysClosed);
@@ -158,7 +277,7 @@ class GetImpl implements GetService {
     }
   }
-  /// It will close as many screens as you define. Times must be> 0;
+  /// Close as many routes as defined by [times]
   void close(int times, [int id]) {
     if ((times == null) || (times < 1)) {
       times = 1;
@@ -170,19 +289,40 @@ class GetImpl implements GetService {
     return back;
   }
-  /// It replaces Navigator.pushReplacement, but needs no context, and it doesn't have the Navigator.pushReplacement
-  /// routes rebuild bug present in Flutter. If for some strange reason you want the default behavior
-  /// of rebuilding every app after a route, use opaque = true as the parameter.
-  Future<T> off<T>(Widget page,
-      {bool opaque = false,
-      Transition transition,
-      bool popGesture,
-      int id,
-      Object arguments,
-      Bindings binding,
-      bool fullscreenDialog = false,
-      preventDuplicates = true,
-      Duration duration}) {
+  /// Pop the current page and pushes a new [page] to the stack
+  ///
+  /// It has the advantage of not needing context,
+  /// so you can call from your business logic
+  ///
+  /// You can set a custom [transition], and a transition [duration].
+  ///
+  /// You can send any type of value to the other route in the [arguments].
+  ///
+  /// Just like native routing in Flutter, you can push a route
+  /// as a [fullscreenDialog],
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// If you want the same behavior of ios that pops a route when the user drag,
+  /// you can set [popGesture] to true
+  ///
+  /// If you're using the [Bindings] api, you must define it here
+  ///
+  /// By default, GetX will prevent you from push a route that you already in,
+  /// if you want to push anyway, set [preventDuplicates] to false
+  Future<T> off<T>(
+    Widget page, {
+    bool opaque = false,
+    Transition transition,
+    bool popGesture,
+    int id,
+    Object arguments,
+    Bindings binding,
+    bool fullscreenDialog = false,
+    preventDuplicates = true,
+    Duration duration,
+  }) {
     if (preventDuplicates && '/${page.runtimeType}' == currentRoute) {
       return null;
     }
@@ -198,17 +338,45 @@ class GetImpl implements GetService {
         transitionDuration: duration ?? defaultDurationTransition));
   }
-  /// It replaces Navigator.pushAndRemoveUntil, but needs no context
-  Future<T> offAll<T>(Widget page,
-      {RoutePredicate predicate,
-      bool opaque = false,
-      bool popGesture,
-      int id,
-      Object arguments,
-      Bindings binding,
-      bool fullscreenDialog = false,
-      Duration duration,
-      Transition transition}) {
+  /// Pop all pages in the stack and pushes a new [page] to it
+  ///
+  /// It has the advantage of not needing context,
+  /// so you can call from your business logic
+  ///
+  /// You can set a custom [transition], and a transition [duration].
+  ///
+  /// You can send any type of value to the other route in the [arguments].
+  ///
+  /// Just like native routing in Flutter, you can push a route
+  /// as a [fullscreenDialog],
+  ///
+  /// [predicate] can be used like this:
+  /// `Get.until(Get.currentRoute == '/home')`so when you get to home page,
+  /// or also like
+  /// `Get.until(!Get.isDialogOpen())`, to make sure the dialog is closed
+  ///
+  /// [id] is for when you are using nested navigation,
+  /// as explained in documentation
+  ///
+  /// If you want the same behavior of ios that pops a route when the user drag,
+  /// you can set [popGesture] to true
+  ///
+  /// If you're using the [Bindings] api, you must define it here
+  ///
+  /// By default, GetX will prevent you from push a route that you already in,
+  /// if you want to push anyway, set [preventDuplicates] to false
+  Future<T> offAll<T>(
+    Widget page, {
+    RoutePredicate predicate,
+    bool opaque = false,
+    bool popGesture,
+    int id,
+    Object arguments,
+    Bindings binding,
+    bool fullscreenDialog = false,
+    Duration duration,
+    Transition transition,
+  }) {
     var route = (Route<dynamic> rota) => false;
     return global(id).currentState.pushAndRemoveUntil(