refactor: simplify singleton and improve NetworkInfo documentation

packages/network_info_plus/network_info_plus/lib/network_info_plus.dart

@@ -14,71 +14,91 @@ export 'src/network_info_plus_linux.dart';
 export 'src/network_info_plus_windows.dart'
     if (dart.library.js_interop) 'src/network_info_plus_web.dart';
 
-/// Discover network info: check WI-FI details and more.
+/// Discovers network information such as Wi-Fi details and IP addresses.
+///
+/// This class is implemented as a singleton to avoid multiple instances
+/// interfering with platform channels.
 class NetworkInfo {
+  /// Internal singleton instance.
+  static final NetworkInfo _instance = NetworkInfo._();
+
   /// Constructs a singleton instance of [NetworkInfo].
   ///
-  /// [NetworkInfo] is designed to work as a singleton.
-  // When a second instance is created, the first instance will not be able to listen to the
-  // EventChannel because it is overridden. Forcing the class to be a singleton class can prevent
-  // misuse of creating a second instance from a programmer.
-  factory NetworkInfo() {
-    _singleton ??= NetworkInfo._();
-    return _singleton!;
-  }
+  /// Creating multiple instances may cause unexpected behavior with
+  /// platform channels, therefore this class enforces a singleton pattern.
+  factory NetworkInfo() => _instance;
 
   NetworkInfo._();
 
-  static NetworkInfo? _singleton;
-
-  // This is to manually endorse Dart implementations until automatic
-  // registration of Dart plugins is implemented. For details see
-  // https://github.com/flutter/flutter/issues/52267.
+  // This manually endorses Dart implementations until automatic
+  // registration of Dart plugins is implemented.
+  // See: https://github.com/flutter/flutter/issues/52267
   static NetworkInfoPlatform get _platform {
     return NetworkInfoPlatform.instance;
   }
 
-  /// Obtains the wifi name (SSID) of the connected network
+  /// Obtains the Wi-Fi name (SSID) of the currently connected network.
   ///
-  /// Please note that it DOESN'T WORK on emulators (returns null).
+  /// Returns `null` if:
+  /// - The device is not connected to Wi-Fi
+  /// - Running on an emulator
+  /// - Required permissions are missing
   ///
-  /// From android 8.0 onwards the GPS must be ON (high accuracy)
-  /// in order to be able to obtain the SSID.
+  /// ⚠️ On Android 8.0+, location services (GPS) must be enabled
+  /// with high accuracy to retrieve the SSID.
   Future<String?> getWifiName() {
     return _platform.getWifiName();
   }
 
-  /// Obtains the wifi BSSID of the connected network.
+  /// Obtains the Wi-Fi BSSID of the currently connected network.
   ///
-  /// Please note that it DOESN'T WORK on emulators (returns null).
+  /// Returns `null` if:
+  /// - The device is not connected to Wi-Fi
+  /// - Running on an emulator
+  /// - Required permissions are missing
   ///
-  /// From Android 8.0 onwards the GPS must be ON (high accuracy)
-  /// in order to be able to obtain the BSSID.
+  /// ⚠️ On Android 8.0+, location services (GPS) must be enabled
+  /// with high accuracy to retrieve the BSSID.
   Future<String?> getWifiBSSID() {
     return _platform.getWifiBSSID();
   }
 
-  /// Obtains the IPv4 address of the connected wifi network
+  /// Obtains the IPv4 address of the connected Wi-Fi network.
+  ///
+  /// Returns `null` if the information is unavailable
+  /// or the platform does not support this feature.
   Future<String?> getWifiIP() {
     return _platform.getWifiIP();
   }
 
-  /// Obtains the IPv6 address of the connected wifi network
+  /// Obtains the IPv6 address of the connected Wi-Fi network.
+  ///
+  /// Returns `null` if the information is unavailable
+  /// or the platform does not support this feature.
   Future<String?> getWifiIPv6() {
     return _platform.getWifiIPv6();
   }
 
-  /// Obtains the submask of the connected wifi network
+  /// Obtains the subnet mask of the connected Wi-Fi network.
+  ///
+  /// Returns `null` if the information is unavailable
+  /// or the platform does not support this feature.
   Future<String?> getWifiSubmask() {
     return _platform.getWifiSubmask();
   }
 
-  /// Obtains the gateway IP address of the connected wifi network
+  /// Obtains the gateway IP address of the connected Wi-Fi network.
+  ///
+  /// Returns `null` if the information is unavailable
+  /// or the platform does not support this feature.
   Future<String?> getWifiGatewayIP() {
     return _platform.getWifiGatewayIP();
   }
 
-  /// Obtains the broadcast of the connected wifi network
+  /// Obtains the broadcast address of the connected Wi-Fi network.
+  ///
+  /// Returns `null` if the information is unavailable
+  /// or the platform does not support this feature.
   Future<String?> getWifiBroadcast() {
     return _platform.getWifiBroadcast();
   }