Merge pull request #535 from Nipodemos/add-BindingsBuilder-docs

[docs] BindingBuilder documentation, refactor in dependency management docs

-- [Simple Instance Manager](#simple-instance-manager)
-- [Options](#options)
-- [Bindings](#bindings)
-  - [How to use](#how-to-use)
-- [SmartManagement](#smartmanagement)
-
-## Simple Instance Manager
+# Dependency Management
+- [Dependency Management](#dependency-management)
+  - [Usage](#usage)
+  - [Instancing methods](#instancing-methods)
+    - [Get.put()](#getput)
+    - [Get.lazyPut](#getlazyput)
+    - [Get.putAsync](#getputasync)
+    - [Get.create](#getcreate)
+  - [Differences between methods:](#differences-between-methods)
+  - [Bindings](#bindings)
+    - [How to use](#how-to-use)
+    - [BindingsBuilder](#bindingsbuilder)
+    - [SmartManagement](#smartmanagement)
+      - [SmartManagement.full](#smartmanagementfull)
+      - [SmartManagement.onlyBuilders](#smartmanagementonlybuilders)
+      - [SmartManagement.keepFactory](#smartmanagementkeepfactory)
+    - [How bindings work under the hood](#how-bindings-work-under-the-hood)
+  - [Notes](#notes)
 
 Get has a simple and powerful dependency manager that allows you to retrieve the same class as your Bloc or Controller with just 1 lines of code, no Provider context, no inheritedWidget:
 
@@ -12,21 +23,13 @@ Get has a simple and powerful dependency manager that allows you to retrieve the
 Controller controller = Get.put(Controller()); // Rather Controller controller = Controller();
 ```
 
-- Note: If you are using Get's State Manager, pay more attention to the bindings api, which will make easier to connect your view to your controller.
-
 Instead of instantiating your class within the class you are using, you are instantiating it within the Get instance, which will make it available throughout your App.
 So you can use your controller (or Bloc class) normally
 
-**Tip:** Get dependency management is decloupled from other parts of the package, so if for example your app is already using a state manager (any one, it doesn't matter), you don't need to rewrite it all, you can use this dependency injection with no problems at all
-
-```dart
-controller.fetchApi();
-```
-
 Imagine that you have navigated through numerous routes, and you need a data that was left behind in your controller, you would need a state manager combined with the Provider or Get_it, correct? Not with Get. You just need to ask Get to "find" for your controller, you don't need any additional dependencies:
 
 ```dart
-Controller controller = Get.find();
+Controller controller = Get.find(); // or final controller = Get.find<Controlelr>();
 //Yes, it looks like Magic, Get will find your controller, and will deliver it to you. You can have 1 million controllers instantiated, Get will always give you the right controller.
 ```
 
@@ -36,24 +39,27 @@ And then you will be able to recover your controller data that was obtained back
 Text(controller.textFromApi);
 ```
 
-Looking for lazy loading? You can declare all your controllers, and it will be called only when someone needs it. You can do this with:
+It is possible to lazyLoad a dependency so that it will be instantiated only when is used. Very useful for computational expensive classes or when you know you will not gonna use that class at that time.
 
 ```dart
-Get.lazyPut<Service>(()=> ApiMock());
-/// ApiMock will only be called when someone uses Get.find<Service> for the first time
+Get.lazyPut<ApiMock>(() => ApiMock());
+/// ApiMock will only be called when someone uses Get.find<ApiMock> for the first time
 ```
 
-If you want to register an asynchronous instance, you can use Get.putAsync.
+If you want to register an asynchronous instance, you can use `Get.putAsync`:
 
 ```dart
 Get.putAsync<SharedPreferences>(() async {
-    final prefs = await SharedPreferences.getInstance();
-    await prefs.setInt('counter', 12345);
-    return prefs;
+  final prefs = await SharedPreferences.getInstance();
+  await prefs.setInt('counter', 12345);
+  return prefs;
 });
 ```
 
-usage:
+- Note: If you are using Get's State Manager, pay more attention to the [Bindings](#bindings) api, which will make easier to connect your view to your controller.
+- Note²: Get dependency management is decloupled from other parts of the package, so if for example your app is already using a state manager (any one, it doesn't matter), you don't need to change that, you can use this dependency injection manager with no problems at all
+
+## Usage
 
 ```dart
 int count = Get.find<SharedPreferences>().getInt('counter');
@@ -70,12 +76,14 @@ Get.delete<Controller>();
 
 Although Getx already delivers very good settings for use, it is possible to refine them even more so that it become more useful to the programmer. The methods and it's configurable parameters are:
 
-- Get.put():
+### Get.put()
+
+The most common way of inserting a dependency. Good for the controllers of your views for example.
 
 ```dart
 Get.put<S>(
   // mandatory: the class that you want to get to save, like a controller or anything
-  // note: that "S" means that it can be anything
+  // note: "S" means that it can be a class of any type
   S dependency
 
   // optional: this is for when you want multiple classess that are of the same type
@@ -96,16 +104,22 @@ Get.put<S>(
   bool overrideAbstract = false,
 
   // optional: allows you to create the dependency using function instead of the dependency itself.
+  // this one is not commonly used
   InstanceBuilderCallback<S> builder,
 )
+
+// Example:
+
+Get.put<LoginController>(LoginController(), permanent: true)
 ```
 
-- Get.lazyPut:
+### Get.lazyPut
+
+With lazyPut, the dependency will be only instantiated when it's called. This is particularly useful if you want to instantiate several classes in just one place, but don't need that instances immediatly
 
 ```dart
 Get.lazyPut<S>(
   // mandatory: a method that will be executed when your class is called for the first time
-  // Example: Get.lazyPut<Controller>( () => Controller() )
   InstanceBuilderCallback builder,
   
   // optional: same as Get.put(), it is used for when you want multiple different instance of a same class
@@ -119,15 +133,29 @@ Get.lazyPut<S>(
   bool fenix = false
   
 )
+
+// example
+Get.lazyPut<FirebaseAuth>(
+  () => {
+  // ... some logic if needed
+    return FirebaseAuth()
+  },
+  tag: Math.random().toString(),
+  fenix: true
+)
+
+// example 2:
+Get.lazyPut<Controller>( () => Controller() )
 ```
 
-- Get.putAsync:
+### Get.putAsync
+
+Since `Get.put()` does not support async methods/classes, you need to use Get.putAsync. The way of declare is equal to Get.lazyPut
 
 ```dart
 Get.putAsync<S>(
 
   // mandatory: an async method that will be executed to instantiate your class
-  // Example: Get.putAsync<YourAsyncClass>( () async => await YourAsyncClass() )
   AsyncInstanceBuilderCallback<S> builder,
 
   // optional: same as Get.put(), it is used for when you want multiple different instance of a same class
@@ -137,9 +165,15 @@ Get.putAsync<S>(
   // optional: same as in Get.put(), used when you need to maintain that instance alive in the entire app
   // defaults to false
   bool permanent = false
+)
+
+// Example
+Get.putAsync<YourAsyncClass>( () async => await YourAsyncClass() )
 ```
 
-- Get.create:
+### Get.create
+
+This one is tricky. A detailed explanation of what this is and the differences between the other one can be found on [Differences between methods:](#differences-between-methods) section
 
 ```dart
 Get.create<S>(
@@ -160,19 +194,19 @@ Get.create<S>(
   bool permanent = true
 ```
 
-### Diferences between methods:
+## Differences between methods
 
 First, let's of the `fenix` of Get.lazyPut and the `permanent` of the other methods.
 
 The fundamental difference between `permanent` and `fenix` is how you want to store your instances.
 Reinforcing: by default, GetX deletes instances when they are not is use.
 It means that: If screen 1 has controller 1 and screen 2 has controller 2 and you remove the first route from stack, (like if you use `Get.off()` or `Get.offName()`) the controller 1 lost it's use so it will be erased.
-But if you want to opt to `permanent:true`, then the controller will not be lost in this transition - which is very usefult for services that you want to keep alive thoughout the entire application.
-`fenix` in the other hand is for services that you don't worry in losing between screen changes, but when you need that service, you expect that it is alive. So basically, it will dispose the unused controller/service/class, but when you need that, it will "recreate from the ashes" a new instance.
+But if you want to opt for using `permanent:true`, then the controller will not be lost in this transition - which is very useful for services that you want to keep alive throughout the entire application.
+`fenix` in the other hand is for services that you don't worry in losing between screen changes, but when you need that service, you expect that it is alive. So basically, it will dispose the unused controller/service/class, but when you need it, it will "recreate from the ashes" a new instance.
 
-Proceeding with the differences between methods: 
+Proceeding with the differences between methods:
 
-- Get.put and Get.putAsync follow the same creation order, with the difference that asyn opt for applying a asynchronous method: those two methods create and initialize the instance. That one is inserted directly in the memory, using the internal method `insert` with the parameters `permanent: false` and `isSingleton: true` (this isSingleton parameter only porpuse is to tell if it is to use the dependency on `dependency` or if it is to use the dependency on `FcBuilderFunc`). After that, `Get.find()` is called that immediately initialize the instances that are on memory.
+- Get.put and Get.putAsync follow the same creation order, with the difference that the second uses an asynchronous method: those two methods create and initialize the instance. That one is inserted directly in the memory, using the internal method `insert` with the parameters `permanent: false` and `isSingleton: true` (this isSingleton parameter only porpuse is to tell if it is to use the dependency on `dependency` or if it is to use the dependency on `FcBuilderFunc`). After that, `Get.find()` is called that immediately initialize the instances that are on memory.
 
 - Get.create: As the name implies, it will "create" your dependency! Similar to `Get.put()`, it also call the internal method `insert` to instancing. But `permanent` became true and `isSingleton` became false (since we are "creating" our dependency, there is no way for it to be a singleton instace, that's why is false). And because it has `permanent: true`, we have by default the benefit of not losing it between screens! Also, `Get.find()` is not called immediately, it wait to be used in the screen to be called. It is created this way to make use of the parameter `permanent`, since then, worth noticing, `Get.create()` was made with the goal of create not shared instances, but don't get disposed, like for example a button in a listView, that you want a unique instance for that list - because of that, Get.create must be used together with GetWidget.
 
@@ -193,19 +227,24 @@ In addition, the Binding class will allow you to have SmartManager configuration
 - Create a class and implements Binding
 
 ```dart
-class HomeBinding implements Bindings {
-
-}
+class HomeBinding implements Bindings {}
 ```
 
 Your IDE will automatically ask you to override the "dependencies" method, and you just need to click on the lamp, override the method, and insert all the classes you are going to use on that route:
 
 ```dart
-class HomeBinding implements Bindings{
+class HomeBinding implements Bindings {
   @override
   void dependencies() {
-    Get.lazyPut<ControllerX>(() => ControllerX());
-    Get.lazyPut<Service>(()=> Api());
+    Get.lazyPut<HomeController>(() => HomeController());
+    Get.put<Service>(()=> Api());
+  }
+}
+
+class DetailsBinding implements Bindings {
+  @override
+  void dependencies() {
+    Get.lazyPut<DetailsController>(() => DetailsController());
   }
 }
 ```
@@ -216,14 +255,24 @@ Now you just need to inform your route, that you will use that binding to make t
 
 ```dart
 getPages: [
-  GetPage(name: '/', page: () => Home(), binding: HomeBinding()),
-]
+  GetPage(
+    name: '/',
+    page: () => HomeView(),
+    binding: HomeBinding(),
+  ),
+  GetPage(
+    name: '/details',
+    page: () => DetailsView(),
+    binding: DetailsBinding(),
+  ),
+];
 ```
 
 - Using normal routes:
 
 ```dart
 Get.to(Home(), binding: HomeBinding());
+Get.to(DetailsView(), binding: DetailsBinding())
 ```
 
 There, you don't have to worry about memory management of your application anymore, Get will do it for you.
@@ -237,17 +286,69 @@ GetMaterialApp(
 );
 ```
 
-## SmartManagement
+### BindingsBuilder
+
+The default way of creating a binding creating a class that implements Bindings.
+But alternatively, you can use `BindingsBuilder` callback so that you can simply use a function to instantiate whatever you desire.
+
+Example:
+
+```dart
+getPages: [
+  GetPage(
+    name: '/',
+    page: () => HomeView(),
+    binding: BindingsBuilder(() => {
+      Get.lazyPut<ControllerX>(() => ControllerX());
+      Get.put<Service>(()=> Api());
+    }),
+  ),
+  GetPage(
+    name: '/details',
+    page: () => DetailsView(),
+    binding: BindingsBuilder(() => {
+      Get.lazyPut<DetailsController>(() => DetailsController());
+    }),
+  ),
+];
+```
+
+That way you can avoid to create one Binding class for each route making this even simpler.
+
+Both ways of doing work perfectly fine and we want you to use what most suit your tastes.
+
+### SmartManagement
+
+GetX by default disposes unused controllers from memory, even if a failure occurs and a widget that uses it is not properly disposed.
+This is what is called the `full` mode of dependency management.
+But if you want to change the way GetX controls the disposal of classes, you have `SmartManagement` class that you can set different behaviors.
+
+#### SmartManagement.full
+
+It is the default one. Dispose classes that are not being used and were not set to be permanent. In the majority of the cases you will want to keep this config untouched. If you new to GetX then don't change this.
+
+#### SmartManagement.onlyBuilders
+With this option, only controllers started in `init:` or loaded into a Binding with `Get.lazyPut` will be disposed.
+
+If you use `Get.put()` or `Get.putAsync()` or any other approach, SmartManagement will not have permissions to exclude this dependency.
 
-Always prefer to use standard SmartManagement (full), you do not need to configure anything for that, Get already gives it to you by default. It will surely eliminate all your disused controllers from memory, as its refined control removes the dependency, even if a failure occurs and a widget that uses it is not properly disposed.
-The "full" mode is also safe enough to be used with StatelessWidget, as it has numerous security callbacks that will prevent a controller from remaining in memory if it is not being used by any widget, and disposition is not important here. However, if you are bothered by the default behavior, or just don't want it to happen, Get offers other, more lenient options for intelligent memory management, such as SmartManagement.onlyBuilders, which will depend on the effective removal of widgets using the controller. tree to remove it, and you can prevent a controller from being deployed using "autoRemove: false" in your GetBuilder/GetX.
-With this option, only controllers started in "init:" or loaded into a Binding with "Get.lazyPut" will be disposed, if you use Get.put or any other approach, SmartManagement will not have permissions to exclude this dependency.
 With the default behavior, even widgets instantiated with "Get.put" will be removed, unlike SmartManagement.onlyBuilders.
-SmartManagement.keepFactory is like SmartManagement.full, with one difference. SmartManagement.full purges the factories from the premises, so that Get.lazyPut() will only be able to be called once and your factory and references will be self-destructing. SmartManagement.keepFactory will remove its dependencies when necessary, however, it will keep the "shape" of these, to make an equal one if you need an instance of that again.
-Instead of using SmartManagement.keepFactory you can use Bindings.
-Bindings creates transitory factories, which are created the moment you click to go to another screen, and will be destroyed as soon as the screen-changing animation happens. It is so little time that the analyzer will not even be able to register it. When you navigate to this screen again, a new temporary factory will be called, so this is preferable to using SmartManagement.keepFactory, but if you don't want to create Bindings, or want to keep all your dependencies on the same Binding, it will certainly help you . Factories take up little memory, they don't hold instances, but a function with the "shape" of that class you want. This is very little, but since the purpose of this lib is to get the maximum performance possible using the minimum resources, Get removes even the factories by default. Use whichever is most convenient for you.
 
-- NOTE: DO NOT USE SmartManagement.keepFactory if you are using multiple Bindings. It was designed to be used without Bindings, or with a single Binding linked in the GetMaterialApp's initialBinding.
+#### SmartManagement.keepFactory
+
+Just like SmartManagement.full, it will remove it's dependencies when it's not being used anymore. However, it will keep the their factory, which means it will recreate the dependency if you need that instance again.
+
+### How bindings work under the hood
+Bindings creates transitory factories, which are created the moment you click to go to another screen, and will be destroyed as soon as the screen-changing animation happens.
+This happens so fast that the analyzer will not even be able to register it.
+When you navigate to this screen again, a new temporary factory will be called, so this is preferable to using SmartManagement.keepFactory, but if you don't want to create Bindings, or want to keep all your dependencies on the same Binding, it will certainly help you.
+Factories take up little memory, they don't hold instances, but a function with the "shape" of that class you want.
+This has a very low cost in memory, but since the purpose of this lib is to get the maximum performance possible using the minimum resources, Get removes even the factories by default.
+Use whichever is most convenient for you.
+
+## Notes
+
+- DO NOT USE SmartManagement.keepFactory if you are using multiple Bindings. It was designed to be used without Bindings, or with a single Binding linked in the GetMaterialApp's initialBinding.
 
-- NOTE2: Using Bindings is completely optional, you can use Get.put() and Get.find() on classes that use a given controller without any problem.
-However, if you work with Services or any other abstraction, I recommend using Bindings for a larger organization.
+- Using Bindings is completely optional, if you want you can use `Get.put()` and `Get.find()` on classes that use a given controller without any problem.
+However, if you work with Services or any other abstraction, I recommend using Bindings for a better organization.

-sdk.dir=/home/jonny/Android/Sdk
-flutter.sdk=/opt/flutter
-flutter.buildMode=debug
-flutter.versionName=1.0.0
-flutter.versionCode=1
\ No newline at end of file