GetInstance docs

- improved comments.

@@ -3,11 +3,33 @@ import 'package:get/src/core/get_interface.dart';
 import 'get_instance.dart';
 import 'get_instance.dart';
 
 
 extension Inst on GetInterface {
 extension Inst on GetInterface {
-  void lazyPut<S>(InstanceBuilderCallback builder,
+  /// Creates a new Instance<S> lazily from the [<S>builder()] callback.
+  ///
+  /// The first time you call [Get.find()], the [builder()] callback will create
+  /// the Instance and persisted as a Singleton (like you would use [Get.put()]).
+  ///
+  /// Using [GetConfig.smartManagement] as [SmartManagement.keepFactory] has the same outcome
+  /// as using [fenix:true] :
+  /// The internal register of [builder()] will remain in memory to recreate the Instance
+  /// if the Instance has been removed with [Get.delete()].
+  /// Therefore, future calls to [Get.find()] will return the same Instance.
+  ///
+  /// If you need to make use of GetxController's life-cycle ([onInit(), onStart(), onClose()])
+  /// [fenix] is a great choice to mix with [GetBuilder()] and [GetX()] widgets, and/or [GetMaterialApp] Navigation.
+  ///
+  /// You could use [Get.lazyPut(fenix:true)] in your app's [main()] instead of [Bindings()] for each [GetPage].
+  /// And the memory management will be similar.
+  ///
+  /// Subsequent calls to [Get.lazyPut()] with the same parameters (<[S]> and optionally [tag]
+  /// will **not** override the original).
+  void lazyPut<S>(InstanceBuilderCallback<S> builder,
       {String tag, bool fenix = false}) {
       {String tag, bool fenix = false}) {
-    return GetInstance().lazyPut<S>(builder, tag: tag, fenix: fenix);
+    GetInstance().lazyPut<S>(builder, tag: tag, fenix: fenix);
   }
   }
 
 
+  /// async version of [Get.put()].
+  /// Awaits for the resolution of the Future from [builder()] parameter and
+  /// stores the Instance returned.
   Future<S> putAsync<S>(AsyncInstanceBuilderCallback<S> builder,
   Future<S> putAsync<S>(AsyncInstanceBuilderCallback<S> builder,
           {String tag, bool permanent = false}) async =>
           {String tag, bool permanent = false}) async =>
       GetInstance().putAsync<S>(builder, tag: tag, permanent: permanent);
       GetInstance().putAsync<S>(builder, tag: tag, permanent: permanent);
@@ -26,19 +48,21 @@ extension Inst on GetInterface {
           {String name, bool permanent = true}) =>
           {String name, bool permanent = true}) =>
       GetInstance().create<S>(builder, name: name, permanent: permanent);
       GetInstance().create<S>(builder, name: name, permanent: permanent);
 
 
-  /// Finds a instance of the required Class<[S]> (or [tag])
-  /// In the case of using Get.[create], it will create an instance
-  /// each time you call [find]
+  /// Finds a Instance of the required Class <[S]>(or [tag])
+  /// In the case of using [Get.create()], it will generate an Instance
+  /// each time you call [Get.find()].
   S find<S>({String tag}) => GetInstance().find<S>(tag: tag);
   S find<S>({String tag}) => GetInstance().find<S>(tag: tag);
 
 
-  /// Injects a Instance [S] in [GetInstance].
+  /// Injects an [Instance<S>] in memory.
   ///
   ///
   /// No need to define the generic type <[S]> as it's inferred from the [dependency]
   /// No need to define the generic type <[S]> as it's inferred from the [dependency]
+  /// parameter.
   ///
   ///
   /// - [dependency] The Instance to be injected.
   /// - [dependency] The Instance to be injected.
   /// - [tag] optionally, use a [tag] as an "id" to create multiple records of the same Type<[S]>
   /// - [tag] optionally, use a [tag] as an "id" to create multiple records of the same Type<[S]>
-  /// - [permanent] keeps the Instance in memory, not following [GetConfig.smartManagement]
-  ///   rules
+  ///   the [tag] does **not** conflict with the same tags used by other [dependencies] Types.
+  /// - [permanent] keeps the Instance in memory and persist it, not following [GetConfig.smartManagement]
+  ///   rules. Although, can be removed by [GetInstance.reset()] and [Get.delete()]
   /// - [builder] If defined, the [dependency] must be returned from here
   /// - [builder] If defined, the [dependency] must be returned from here
   S put<S>(S dependency,
   S put<S>(S dependency,
           {String tag,
           {String tag,
@@ -50,15 +74,21 @@ extension Inst on GetInterface {
   /// Clears all registered instances (and/or tags).
   /// Clears all registered instances (and/or tags).
   /// Even the persistent ones.
   /// Even the persistent ones.
   ///
   ///
-  /// [clearFactory] clears the callbacks registered by [lazyPut]
-  /// [clearRouteBindings] clears Instances associated with routes.
+  /// - [clearFactory] clears the callbacks registered by [Get.lazyPut()]
+  /// - [clearRouteBindings] clears Instances associated with Routes when using
+  ///   [GetMaterialApp].
   bool reset({bool clearFactory = true, bool clearRouteBindings = true}) =>
   bool reset({bool clearFactory = true, bool clearRouteBindings = true}) =>
       GetInstance().reset(
       GetInstance().reset(
           clearFactory: clearFactory, clearRouteBindings: clearRouteBindings);
           clearFactory: clearFactory, clearRouteBindings: clearRouteBindings);
 
 
-  /// Delete class instance on [S], cleaning the memory
-  Future<bool> delete<S>({String tag, String key}) async =>
-      GetInstance().delete<S>(tag: tag, key: key);
+  /// Deletes the Instance<[S]>, cleaning the memory and closes any open
+  /// controllers ([DisposableInterface]).
+  ///
+  /// - [tag] Optional "tag" used to register the Instance
+  Future<bool> delete<S>({String tag}) async =>
+      GetInstance().delete<S>(tag: tag);
 
 
+  /// Check if a Class Instance<[S]> (or [tag]) is registered in memory.
+  /// - [tag] optional, if you use a [tag] to register the Instance.
   bool isRegistered<S>({String tag}) => GetInstance().isRegistered<S>(tag: tag);
   bool isRegistered<S>({String tag}) => GetInstance().isRegistered<S>(tag: tag);
 }
 }

@@ -18,23 +18,47 @@ class GetInstance {
   static GetInstance _getInstance;
   static GetInstance _getInstance;
 
 
   /// Holds references to every registered Instance when using
   /// Holds references to every registered Instance when using
-  /// Get.[put]
+  /// [Get.put()]
   static Map<String, _InstanceBuilderFactory> _singl = {};
   static Map<String, _InstanceBuilderFactory> _singl = {};
 
 
   /// Holds a reference to every registered callback when using
   /// Holds a reference to every registered callback when using
-  /// Get.[lazyPut]
+  /// [Get.lazyPut()]
   static Map<String, _Lazy> _factory = {};
   static Map<String, _Lazy> _factory = {};
 
 
+  /// Holds a reference to [GetConfig.currentRoute] when the Instance was
+  /// created to manage the memory.
   static Map<String, String> _routesKey = {};
   static Map<String, String> _routesKey = {};
 
 
   static GetQueue _queue = GetQueue();
   static GetQueue _queue = GetQueue();
 
 
-  void lazyPut<S>(InstanceBuilderCallback builder,
+  /// Creates a new Instance<S> lazily from the [<S>builder()] callback.
+  ///
+  /// The first time you call [Get.find()], the [builder()] callback will create
+  /// the Instance and persisted as a Singleton (like you would use [Get.put()]).
+  ///
+  /// Using [GetConfig.smartManagement] as [SmartManagement.keepFactory] has the same outcome
+  /// as using [fenix:true] :
+  /// The internal register of [builder()] will remain in memory to recreate the Instance
+  /// if the Instance has been removed with [Get.delete()].
+  /// Therefore, future calls to [Get.find()] will return the same Instance.
+  ///
+  /// If you need to make use of GetxController's life-cycle ([onInit(), onStart(), onClose()])
+  /// [fenix] is a great choice to mix with [GetBuilder()] and [GetX()] widgets, and/or [GetMaterialApp] Navigation.
+  ///
+  /// You could use [Get.lazyPut(fenix:true)] in your app's [main()] instead of [Bindings()] for each [GetPage].
+  /// And the memory management will be similar.
+  ///
+  /// Subsequent calls to [Get.lazyPut()] with the same parameters (<[S]> and optionally [tag]
+  /// will **not** override the original).
+  void lazyPut<S>(InstanceBuilderCallback<S> builder,
       {String tag, bool fenix = false}) {
       {String tag, bool fenix = false}) {
     String key = _getKey(S, tag);
     String key = _getKey(S, tag);
     _factory.putIfAbsent(key, () => _Lazy(builder, fenix));
     _factory.putIfAbsent(key, () => _Lazy(builder, fenix));
   }
   }
 
 
+  /// async version of [Get.put()].
+  /// Awaits for the resolution of the Future from [builder()] parameter and
+  /// stores the Instance returned.
   Future<S> putAsync<S>(AsyncInstanceBuilderCallback<S> builder,
   Future<S> putAsync<S>(AsyncInstanceBuilderCallback<S> builder,
       {String tag, bool permanent = false}) async {
       {String tag, bool permanent = false}) async {
     return put<S>(await builder(), tag: tag, permanent: permanent);
     return put<S>(await builder(), tag: tag, permanent: permanent);
@@ -196,10 +220,9 @@ class GetInstance {
       return _singl[key].getDependency() as S;
       return _singl[key].getDependency() as S;
     } else {
     } else {
       if (!_factory.containsKey(key))
       if (!_factory.containsKey(key))
-        throw '"$S" not found. You need to call "Get.put<$S>($S())"';
+        throw '"$S" not found. You need to call "Get.put($S())" or "Get.lazyPut(()=>$S())"';
 
 
-      // TODO: This message is not clear
-      GetConfig.log('"$S" instance was created at that time');
+      GetConfig.log('Lazy instance "$S" created');
 
 
       S _value = put<S>(_factory[key].builder() as S);
       S _value = put<S>(_factory[key].builder() as S);
 
 
@@ -214,6 +237,8 @@ class GetInstance {
     }
     }
   }
   }
 
 
+  /// Generates the key based on [type] (and optionally a [name])
+  /// to register an Instance Builder in the hashmap.
   String _getKey(Type type, String name) {
   String _getKey(Type type, String name) {
     return name == null ? type.toString() : type.toString() + name;
     return name == null ? type.toString() : type.toString() + name;
   }
   }
@@ -239,6 +264,20 @@ class GetInstance {
 
 
   /// Delete registered Class Instance [S] (or [tag]) and, closes any open
   /// Delete registered Class Instance [S] (or [tag]) and, closes any open
   /// controllers [DisposableInterface], cleans up the memory
   /// controllers [DisposableInterface], cleans up the memory
+  ///
+  /// /// Deletes the Instance<[S]>, cleaning the memory.
+  //  ///
+  //  /// - [tag] Optional "tag" used to register the Instance
+  //  /// - [key] For internal usage, is the processed key used to register
+  //  ///   the Instance. **don't use** it unless you know what you are doing.
+
+  /// Deletes the Instance<[S]>, cleaning the memory and closes any open
+  /// controllers ([DisposableInterface]).
+  ///
+  /// - [tag] Optional "tag" used to register the Instance
+  /// - [key] For internal usage, is the processed key used to register
+  ///   the Instance. **don't use** it unless you know what you are doing.
+  /// - [force] Will delete an Instance even if marked as [permanent].
   Future<bool> delete<S>({String tag, String key, bool force = false}) async {
   Future<bool> delete<S>({String tag, String key, bool force = false}) async {
     final newKey = key ?? _getKey(S, tag);
     final newKey = key ?? _getKey(S, tag);
 
 
@@ -277,10 +316,13 @@ class GetInstance {
     });
     });
   }
   }
 
 
-  /// Check if a Class instance [S] (or [tag]) is registered.
+  /// Check if a Class Instance<[S]> (or [tag]) is registered in memory.
+  /// - [tag] optional, if you use a [tag] to register the Instance.
   bool isRegistered<S>({String tag}) => _singl.containsKey(_getKey(S, tag));
   bool isRegistered<S>({String tag}) => _singl.containsKey(_getKey(S, tag));
 
 
-  /// Check if Class instance [S] (or [tag]) is prepared to be used.
+  /// Checks if a lazy factory callback that returns an Instance<[S]>
+  /// is registered.
+  /// - [tag] optional, if you use a [tag] to register the Instance.
   bool isPrepared<S>({String tag}) => _factory.containsKey(_getKey(S, tag));
   bool isPrepared<S>({String tag}) => _factory.containsKey(_getKey(S, tag));
 }
 }
 
 
@@ -321,5 +363,6 @@ class _InstanceBuilderFactory<S> {
 class _Lazy {
 class _Lazy {
   bool fenix;
   bool fenix;
   InstanceBuilderCallback builder;
   InstanceBuilderCallback builder;
+
   _Lazy(this.builder, this.fenix);
   _Lazy(this.builder, this.fenix);
 }
 }