Merge pull request #363 from Nipodemos/docs_update

[docs] more docs for dependency management

@@ -24,6 +24,7 @@
   - [Otras API avanzadas y configuraciones manuales](#otras-api-avanzadas-y-configuraciones-manuales)
     - [Configuraciones globales opcionales](#configuraciones-globales-opcionales)
 - [Rompiendo cambios desde 2.0](#rompiendo-cambios-desde-20)
+- [¿Por qué Getx?](#por-qué-getx)
 
 # Sobre GetX
 
@@ -64,7 +65,9 @@ El proyecto "contador" creado por defecto en un nuevo proyecto en Flutter tiene
 void main() => runApp(GetMaterialApp(home: Home()));
 ```
 
-Nota: esto no modifica el MaterialApp del Flutter, GetMaterialApp no es una MaterialApp modificado, es solo un Widget preconfigurado, que tiene como child un MaterialApp por defecto. Puede configurar esto manualmente, pero definitivamente no es necesario. GetMaterialApp creará rutas, las inyectará, inyectará traducciones, inyectará todo lo que necesita para la navegación de rutas. Si usa Get solo para la gestión de estado o dependencias, no es necesario usar GetMaterialApp. GetMaterialApp es necesario para rutas, snackbars, internacionalización, bottomSheets, diálogos y APIs de alto nivel relacionadas con rutas y ausencia de contexto.
+**Nota**: esto no modifica el MaterialApp del Flutter, GetMaterialApp no es una MaterialApp modificado, es solo un Widget preconfigurado, que tiene como child un MaterialApp por defecto. Puede configurar esto manualmente, pero definitivamente no es necesario. GetMaterialApp creará rutas, las inyectará, inyectará traducciones, inyectará todo lo que necesita para la navegación de rutas. Si usa Get solo para la gestión de estado o dependencias, no es necesario usar GetMaterialApp. GetMaterialApp es necesario para rutas, snackbars, internacionalización, bottomSheets, diálogos y APIs de alto nivel relacionadas con rutas y ausencia de contexto.
+
+**Note²:** This step in only necessary if you gonna use route management (`Get.to()`, `Get.back()` and so on). If you not gonna use it then it is not necessary to do step 1
 
 - Paso 2:  
 Cree su clase con la lógica de negocio colocando todas las variables, métodos y controladores dentro de ella. Puede hacer que cualquier variable sea observable usando un simple ".obs".
@@ -426,6 +429,7 @@ GetMaterialApp(
   ]
 )
 ```
+
 # ¿Por qué Getx?
 
 1- Después de una actualización de Flutter, muchos paquetes suelen romperse. A veces se producen errores de compilación, errores de los que aún no hay respuestas y el desarrollador necesita saber el origen del error, poder rastrearlo, y solo entonces intentar abrir un issue en el repositorio correspondiente, para finalmente ver su problema resuelto. Getx centraliza los principales recursos para el desarrollo (gestión de estado, dependencia y rutas), lo que le permite agregar un único paquete a su pubspec y comenzar a trabajar. Después de una actualización de Flutter, lo único que debe hacer es actualizar la dependencia Get y ponerse a trabajar. Get también resuelve problemas de compatibilidad. ¿Cuántas veces una versión de un paquete no es compatible con la versión de otro, porque una usa una dependencia en una versión y la otra en otra? Tampoco es una preocupación usando Get, ya que todo estará en el mismo paquete y será totalmente compatible.

@@ -20,7 +20,8 @@
 
 [**Telegram (Portuguese)**](https://t.me/joinchat/PhdbJRmsZNpAqSLJL6bH7g)
 
-# Topics:
+# Topics
+
 - [**About Get**](#about-get)
 - [**Installing**](#installing)
 - [**The Three pillars**](#the-three-pillars)
@@ -36,7 +37,7 @@
   - [Other Advanced APIs](#other-advanced-apis)
     - [Optional Global Settings and Manual configurations](#optional-global-settings-and-manual-configurations)
 - [**Breaking changes from 2.0**](#breaking-changes-from-20)
-- [**Why GetX?**](#why-getx?)
+- [**Why GetX?**](#why-getx)
 
 # About Get
 
@@ -80,6 +81,7 @@ void main() => runApp(GetMaterialApp(home: Home()));
 ```
 
 - Note: this does not modify the MaterialApp of the Flutter, GetMaterialApp is not a modified MaterialApp, it is just a pre-configured Widget, which has the default MaterialApp as a child. You can configure this manually, but it is definitely not necessary. GetMaterialApp will create routes, inject them, inject translations, inject everything you need for route navigation. If you use Get only for state management or dependency management, it is not necessary to use GetMaterialApp. GetMaterialApp is necessary for routes, snackbars, internationalization, bottomSheets, dialogs, and high-level apis related to routes and absence of context.
+- Note²: This step in only necessary if you gonna use route management (`Get.to()`, `Get.back()` and so on). If you not gonna use it then it is not necessary to do step 1
 
 - Step 2:
 Create your business logic class and place all variables, methods and controllers inside it.
@@ -185,17 +187,19 @@ Noticed that you didn't had to use context to do any of these things? That's one
 
 See a more in-depth explanation of dependency management [here](./docs/en_US/dependency_management.md)
 
-- Note: If you are using Get's State Manager, you don't have to worry about that, just read for information, but pay more attention to the bindings api, which will do all of this automatically for you.
-
-Are you already using Get and want to make your project as lean as possible? 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:
+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:
 
 ```dart
 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 class Bloc) 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();
 ```

@@ -30,7 +30,7 @@
   - [RxController e GetBuilder se uniram](#rxcontroller-e-getbuilder-se-uniram)
   - [Rotas nomeadas](#rotas-nomeadas)
     - [Porque essa mudança](#porque-essa-mudança)
-- [Porque eu fiz esse package](#porque-eu-fiz-esse-package)
+- [Por que GetX](#por-que-getx)
 
 # Sobre Get
 
@@ -42,7 +42,7 @@
 - Get vai economizar horas de desenvolvimento, e vai extrair a performance máxima que sua aplicação pode entregar, enquanto é fácil para iniciantes e preciso para experts.
 - Navegue por rotas sem `context`, abra `Dialog`s, `Snackbar`s ou `BottomSheet`s de qualquer lugar no código, gerencie estados e injete dependências de uma forma simples e prática.
 - Get é seguro, estável, atualizado e oferece uma enorme gama de APIs que não estão presentes no framework padrão.
-- GetX não é um `bloc` da vida. Ele tem uma variedade de recursos que te permite começar a programar sem se preocupar com nada, mas cada um desses recursos estão em um container separado, ou seja, nenhuma depende da outra para funcionar. Elas só são inicializadas após o uso. Se você usa apenas o gerenciador de estado, apenas ele será compilado. Teste você mesmo, vá no repositório de benchmark do getX e perceberá: usando somente o gerenciador de estado do Get, a aplicação ficou mais leve do que outros projetos que também estão usando só o gerenciador de estado, porque nada que não seja usado será compilado no seu código, e cada recuro do GetX foi feito para ser muito leve. O mérito vem também do AOT do próprio Flutter que é incrível, e consegue eliminar recursos não utilizados de uma forma que nenhum outro framework consegue.
+- GetX é desacoplado. Ele tem uma variedade de recursos que te permite começar a programar sem se preocupar com nada, mas cada um desses recursos estão em um container separado, ou seja, nenhuma depende da outra para funcionar. Elas só são inicializadas após o uso. Se você usa apenas o gerenciador de estado, apenas ele será compilado. Teste você mesmo, vá no repositório de benchmark do getX e perceberá: usando somente o gerenciador de estado do Get, a aplicação ficou mais leve do que outros projetos que também estão usando só o gerenciador de estado, porque nada que não seja usado será compilado no seu código, e cada recuro do GetX foi feito para ser muito leve. O mérito vem também do AOT do próprio Flutter que é incrível, e consegue eliminar recursos não utilizados de uma forma que nenhum outro framework consegue.
 
 **GetX faz seu desenvolvimento mais produtivo, mas quer deixá-lo mais produtivo ainda? Adicione a extensão [GetX extension](https://marketplace.visualstudio.com/items?itemName=get-snippets.get-snippets) no seu VSCode**. Não disponível para outras IDEs por enquanto.
 
@@ -75,9 +75,9 @@ import 'package:get/get.dart';
 
 ## Gerenciamento de estado
 
-Veja uma explicação mais completa do gerenciamento de estado [aqui](./docs/pt_BR/route_management.md)
+**Veja uma explicação mais completa do gerenciamento de estado [aqui](./docs/pt_BR/route_management.md)**
 
-O app 'Counter' criado por padrão no com o comando `flutter create` tem mais de 100 linhas(incluindo os comentários). Para demonstrar o poder do Get, irei demonstrar como fazer o mesmo 'Counter' mudando o estado em cada toque trocando entre páginas e compartilhando o estado entre telas. Tudo de forma organizada, separando a lógica de negócio da View, COM SOMENTE 26 LINHAS INCLUINDO COMENTÁRIOS
+O app 'Counter' criado por padrão no flutter com o comando `flutter create` tem mais de 100 linhas(incluindo os comentários). Para demonstrar o poder do Get, irei demonstrar como fazer o mesmo 'Counter' mudando o estado em cada toque trocando entre páginas e compartilhando o estado entre telas. Tudo de forma organizada, separando a lógica de negócio da View, COM SOMENTE 26 LINHAS INCLUINDO COMENTÁRIOS
 
 - Passo 1:
 Troque `MaterialApp` para `GetMaterialApp`
@@ -91,6 +91,7 @@ void main() => runApp(GetMaterialApp(home: Home()));
   - Snackbars/bottomsheets/dialogs
   - apis relacionadas a rotas e a ausência de `context`
   - Internacionalização
+- **Obs²:** Esse passo só é necessário se você for usar o gerenciamento de rotas (`Get,to()`, `Get.back()` e assim por diante), Se você não vai usar isso então não é necessário seguir o passo 1
 
 - Passo 2:
 Cria a sua classe de regra de negócio e coloque todas as variáveis, métodos e controllers dentro dela.
@@ -486,4 +487,3 @@ GetMaterialApp(
 
 4- Desacoplamento real. Você já deve ter ouvido o conceito "separar a view da lógica de negócios". Isso não é uma peculiaridade do BLoC, MVC, MVVM, e qualquer outro padrão existente no mercado tem esse conceito. No entanto, muitas vezes esse conceito pode ser mitigado no Flutter por conta do uso do context.
 Se você precisa de context para localizar um InheritedWidget, você precisa disso na view, ou passar o context por parametro. Eu particularmente acho essa solução muito feia, e para trabalhar em equipes teremos sempre uma dependencia da lógica de negócios da View. Getx é pouco ortodoxo com a abordagem padrão, e apesar de não proibir totalmente o uso de StatefulWidgets, InitState, e etc, ele tem sempre uma abordagem similar que pode ser mais limpa. Os controllers tem ciclos de vida, e quando você precisa fazer uma solicitação APIREST por exemplo, você não depende de nada da view. Você pode usar onInit para iniciar a chamada http, e quando os dados chegarem, as variáveis serão preenchidas. Como GetX é totalmente reativo (de verdade, e trabalha sob streams), assim que os itens forem preenchidos, automaticamente será atualizado na view todos os widgets que usam aquela variável. Isso permite que as pessoas especialistas em UI trabalhem apenas com widgets, e não precisem enviar nada para a lógica de negócio além de eventos do usuário (como clicar em um botão), enquanto as pessoas que trabalham com a lógica de negócios ficarão livres para criar e testar a lógica de negócios separadamente.  
-

-
 # Dependency Management
 
 ## Simple Instance Manager
 
-- Note: If you are using Get's State Manager, you don't have to worry about that, just read for information, but pay more attention to the bindings api, which will do all of this automatically for you.
-
-Are you already using Get and want to make your project as lean as possible? 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:
+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:
 
 ```dart
 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 class Bloc) normally
+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();
@@ -61,6 +62,79 @@ To remove a instance of Get:
 Get.delete<Controller>();
 ```
 
+## Options
+
+When you use Get.put, lazyPut and putAsync you will have some options that you can change if you want
+
+- On Get.put():
+
+```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
+  S dependency
+
+  // optional: this is for when you want multiple classess that are of the same type
+  // since you normally get a class by using Get.find<Controller>(),
+  // you need to use tag to tell which instance you need
+  // must be unique string
+  String tag,
+
+  // optional: by default, get will dispose instances after they are not used anymore (example,
+  // the controller of a view that is closed), but you might need that the instance
+  // to be kept there throughout the entire app, like an instance of sharedPreferences or something
+  // so you use this
+  // defaults to false
+  bool permanent = false,
+
+  // optional: allows you after using an abstract class in a test, replace it with another one and follow the test.
+  // defaults to false
+  bool overrideAbstract = false,
+
+  // optional: allows you to create the dependency using function instead of the dependency itself.
+  FcBuilderFunc<S> builder,
+)
+```
+
+- On Get.lazyPut:
+
+```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() )
+  FcBuilderFunc builder,
+  
+  // optional: same as Get.put(), it is used for when you want multiple different instance of a same class
+  // must be unique
+  String tag,
+
+  // optional: It is similar to "permanent", the difference is that the instance is discarded when
+  // is not being used, but when it's use is needed again, Get will recreate the instance
+  // just the same as "SmartManagement.keepFactory" in the bindings api
+  // defaults to false
+  bool fenix = false
+  
+)
+```
+
+- On Get.putAsync:
+
+```dart
+Get.putAsync<S>(
+
+  // mandatory: an async method that will be executed to instantiate your class
+  // Example: Get.putAsync<YourAsyncClass>( () async => await YourAsyncClass() )
+  FcBuilderFuncAsync<S> builder,
+
+  // optional: same as Get.put(), it is used for when you want multiple different instance of a same class
+  // must be unique
+  String tag,
+
+  // 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
+```
+
 ## Bindings
 
 One of the great differentials of this package, perhaps, is the possibility of full integration of the routes, state manager and dependency manager.
@@ -76,7 +150,9 @@ 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:

@@ -62,6 +62,79 @@ Para eliminar una instancia de GetX:
 Get.delete<Controller>();
 ```
 
+## Options
+
+When you use Get.put, lazyPut and putAsync you will have some options that you can change if you want
+
+- On Get.put():
+
+```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
+  S dependency
+
+  // optional: this is for when you want multiple classess that are of the same type
+  // since you normally get a class by using Get.find<Controller>(),
+  // you need to use tag to tell which instance you need
+  // must be unique string
+  String tag,
+
+  // optional: by default, get will dispose instances after they are not used anymore (example,
+  // the controller of a view that is closed), but you might need that the instance
+  // to be kept there throughout the entire app, like an instance of sharedPreferences or something
+  // so you use this
+  // defaults to false
+  bool permanent = false,
+
+  // optional: allows you after using an abstract class in a test, replace it with another one and follow the test.
+  // defaults to false
+  bool overrideAbstract = false,
+
+  // optional: allows you to create the dependency using function instead of the dependency itself.
+  FcBuilderFunc<S> builder,
+)
+```
+
+- On Get.lazyPut:
+
+```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() )
+  FcBuilderFunc builder,
+  
+  // optional: same as Get.put(), it is used for when you want multiple different instance of a same class
+  // must be unique
+  String tag,
+
+  // optional: It is similar to "permanent", the difference is that the instance is discarded when
+  // is not being used, but when it's use is needed again, Get will recreate the instance
+  // just the same as "SmartManagement.keepFactory" in the bindings api
+  // defaults to false
+  bool fenix = false
+  
+)
+```
+
+- On Get.putAsync:
+
+```dart
+Get.putAsync<S>(
+
+  // mandatory: an async method that will be executed to instantiate your class
+  // Example: Get.putAsync<YourAsyncClass>( () async => await YourAsyncClass() )
+  FcBuilderFuncAsync<S> builder,
+
+  // optional: same as Get.put(), it is used for when you want multiple different instance of a same class
+  // must be unique
+  String tag,
+
+  // 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
+```
+
 ## Bindings
 
 Una de las grandes diferencias de este paquete, tal vez, es la posibilidad de una integración completa de las rutas, gestor de estado y dependencias.

+# Gerenciamento de dependência
 
 ## Gerenciamento de dependências simples
 
-* Nota: Se você está usando o gerenciado de estado do Get, você não precisa se preocupar com isso, só leia a documentação, mas dê uma atenção a api `Bindings`, que vai fazer tudo isso automaticamente para você.
-
 Já está usando o Get e quer fazer seu projeto o melhor possível? Get tem um gerenciador de dependência simples e poderoso que permite você pegar a mesma classe que seu Bloc ou Controller com apenas uma linha de código, sem Provider context, sem inheritedWidget:
 
 ```dart
 Controller controller = Get.put(Controller()); // Em vez de Controller controller = Controller();
 ```
 
+* Nota: Se você está usando o gerenciado de estado do Get, você não precisa se preocupar com isso, só leia a documentação, mas dê uma atenção a api `Bindings`, que vai fazer tudo isso automaticamente para você.
+
 Em vez de instanciar sua classe dentro da classe que você está usando, você está instanciando ele dentro da instância do Get, que vai fazer ele ficar disponível por todo o App
 
 Para que então você possa usar seu controller (ou uma classe Bloc) normalmente
 
+**Tip:** O gerenciamento de dependência do get é desaclpado de outras partes do package, então se por exemplo seu aplicativo já está usando um outro gerenciador de estado (qualquer um, não importa), você não precisa de reescrever tudo, pode simplesmente usar só a injeção de dependência sem problemas
+
 ```dart
 controller.fetchApi();
 ```
@@ -62,6 +65,78 @@ Para remover a instância do Get:
 Get.delete<Controller>();
 ```
 
+## Opções
+
+Quando você usa Get.put, lazyPut e putAsync, existe algumas opções que você pode alterar se quiser
+
+- No Get.put():
+
+```dart
+Get.put<S>(
+  // obrigatório: a classe que você quer salvar, como um controller ou qualquer outra coisa
+  // obs: Esse "S" significa que pode ser qualquer coisa
+  S dependency
+
+  // opcional: isso é pra quando você quer múltiplas classess que são do mesmo tipo
+  // já que você normalmente pega usando "Get.find<Controller>()",
+  // você precisa usar uma tag para dizer qual das instâncias vc precisa
+  // precisa ser uma string única
+  String tag,
+
+  // opcional: por padrão, get vai descartar as instâncias quando elas não são mais usadas (exemplo,
+  // o controller de uma view que foi fechada) // Mas talvez você precisa quea instância seja mantida por todo o app, como a instância do SharedPreferences por exemplo
+  // então vc usa isso
+  // padrão: false
+  bool permanent = false,
+
+  // opcional: permite que depois de usar uma classe abstrata num teste,
+  // trocar por outra e continuar com o teste
+  // padrão: false
+  bool overrideAbstract = false,
+
+  // opcional: permite criar a dependência usando uma função em vez da dependênia em si
+  FcBuilderFunc<S> builder,
+)
+```
+
+- No Get.lazyPut:
+
+```dart
+Get.lazyPut<S>(
+  // obrigatório: um método que vai ser executado quando sua classe é chamada pela primeira vez
+  // Exemplo: "Get.lazyPut<Controller>( () => Controller()
+  FcBuilderFunc builder,
+  
+  // opcional: igual ao Get.put(), é usado quando você precisa de múltiplas instâncias de uma mesma classe
+  // precisa ser uma string única
+  String tag,
+
+  // opcional: é similar a "permanent", mas a instância é descartada quando
+  // não é mais usada e é refeita quando precisa ser usada novamente
+  // Assim como a opção SmartManagement.keepFactory na api Bindings
+  // padrão: false
+  bool fenix = false
+  
+)
+```
+
+- No Get.putAsync:
+
+```dart
+Get.putAsync<S>(
+  // Obrigatório: um método assíncrono que vai ser executado para instanciar sua classe
+  // Exemplo: Get.putAsyn<YourAsyncClass>( () async => await YourAsyncClass() )
+  FcBuilderFuncAsync<S> builder,
+
+  // opcional: igual ao Get.put(), é usado quando você precisa de múltiplas instâncias de uma mesma classe
+  // precisa ser uma string única
+  String tag,
+
+  // opcional: igual ao Get.put(), usado quando você precisa manter a instância ativa no app inteiro.
+  // padrão: false
+  bool permanent = false
+```
+
 ## Bindings
 
 Um dos grandes diferenciais desse package, talvez, seja a possibilidade de integração total com rotas, gerenciador de estado e gerenciador de dependências.