better documentation added to comply with public_member_api_docs

Author: Csongor Keller

analysis_options.yaml

@@ -0,0 +1,3 @@
+linter:
+  rules:
+    - public_member_api_docs

example/lib/main.dart

@@ -5,7 +5,13 @@ void main() {
   runApp(const MyApp());
 }
 
+/// A simple Flutter application that demonstrates the usage of prebuilt widgets.
+///
+/// This widget is the root of the application and sets up the main [MaterialApp].
+
 class MyApp extends StatelessWidget {
+  /// The [MyApp] class is a stateless widget that represents the entire application.
+  /// It is marked as `const` to indicate that it is immutable and can be instantiated as a compile-time constant.
   const MyApp({super.key});
 
   @override

example/lib/modules/location_view_widget.dart

@@ -1,14 +1,42 @@
 import 'package:flutter/material.dart';
 import 'package:intl/intl.dart';
 
+/// A widget that displays a location view with a title and the current date.
+///
+/// The [LocationViewWidget] is a stateless widget that takes a [title] and a [color]
+/// as required parameters. It displays the [title] in uppercase with a specified
+/// [color] and the current date and time in the format 'yyyy/MM/dd – kk:mm'.
+///
+/// {@tool snippet}
+/// This example shows how to use the [LocationViewWidget] with a title and color:
+///
+/// ```dart
+/// LocationViewWidget(
+///   title: 'New York',
+///   color: Colors.blue,
+/// )
+/// ```
+/// {@end-tool}
+///
+/// The [title] is displayed in uppercase with a font size of 40 and a font weight
+/// of 300. The current date and time are displayed below the title.
+///
+/// See also:
+///  * [DateFormat], which is used to format the current date and time.
 class LocationViewWidget extends StatelessWidget {
+  /// Creates a [LocationViewWidget].
+  ///
+  /// The [title] and [color] parameters must not be null.
   const LocationViewWidget({
     super.key,
     required this.title,
     required this.color,
   });
 
+  /// The color to use for the title text.
   final Color color;
+
+  /// The title to display in the widget.
   final String title;
 
   @override

example/lib/modules/weather_summary_widget.dart

@@ -1,7 +1,24 @@
 import 'package:flutter/material.dart';
 import 'package:transparent_image/transparent_image.dart';
 
+/// A widget that displays a summary of the weather information.
+///
+/// The [WeatherSummary] widget shows an image representing the weather,
+/// the current temperature, maximum and minimum temperatures, humidity,
+/// and pressure.
+///
+/// The widget requires the following parameters:
+/// - [imageUrl]: The URL of the image representing the weather.
+/// - [currentTemperature]: The current temperature.
+/// - [color]: The color to be used for the text and icons.
+/// - [maxTemperature]: The maximum temperature.
+/// - [minTemperature]: The minimum temperature.
+/// - [humidity]: The humidity percentage.
+/// - [pressure]: The atmospheric pressure in hPa.
 class WeatherSummary extends StatelessWidget {
+  /// The [WeatherSummary] widget shows an image representing the weather,
+  /// the current temperature, maximum and minimum temperatures, humidity,
+  /// and pressure.
   const WeatherSummary({
     super.key,
     required this.imageUrl,
@@ -13,14 +30,31 @@ class WeatherSummary extends StatelessWidget {
     required this.pressure,
   });
 
+  /// The color to be used for the text and icons.
   final Color color;
+
+  /// The current temperature.
   final String currentTemperature;
+
+  /// The humidity percentage.
   final String humidity;
+
+  /// The URL of the image representing the weather.
   final String imageUrl;
+
+  /// The maximum temperature.
   final String maxTemperature;
+
+  /// The minimum temperature.
   final String minTemperature;
+
+  /// The atmospheric pressure in hPa.
   final String pressure;
 
+  /// Builds a row displaying an icon and a temperature.
+  ///
+  /// The [icon] parameter specifies the icon to be displayed.
+  /// The [temperature] parameter specifies the temperature to be displayed.
   Widget _buildMinMaxRow({
     required IconData icon,
     required String temperature,
@@ -38,6 +72,10 @@ class WeatherSummary extends StatelessWidget {
     );
   }
 
+  /// Builds a row displaying the humidity and pressure.
+  ///
+  /// The [humidity] parameter specifies the humidity percentage to be displayed.
+  /// The [pressure] parameter specifies the atmospheric pressure to be displayed.
   Widget _buildHumidutyAndPressureRow({
     required String humidity,
     required String pressure,
@@ -100,22 +138,17 @@ class WeatherSummary extends StatelessWidget {
             mainAxisAlignment: MainAxisAlignment.spaceEvenly,
             children: [
               Container(
-                child: _buildMinMaxRow(
-                    icon: Icons.arrow_drop_up_sharp,
-                    temperature: maxTemperature),
+                child: _buildMinMaxRow(icon: Icons.arrow_drop_up_sharp, temperature: maxTemperature),
               ),
               Container(
-                child: _buildMinMaxRow(
-                    icon: Icons.arrow_drop_down_sharp,
-                    temperature: minTemperature),
+                child: _buildMinMaxRow(icon: Icons.arrow_drop_down_sharp, temperature: minTemperature),
               ),
             ],
           ),
         ),
         Padding(
           padding: const EdgeInsets.only(top: 20),
-          child: _buildHumidutyAndPressureRow(
-              humidity: humidity, pressure: pressure),
+          child: _buildHumidutyAndPressureRow(humidity: humidity, pressure: pressure),
         )
       ],
     );

example/lib/screens/prebuilt_functions_demo_screen.dart

@@ -1,9 +1,13 @@
+// ignore_for_file: unused_element
+
 import 'package:example/modules/location_view_widget.dart';
 import 'package:example/modules/weather_summary_widget.dart';
 import 'package:flutter/material.dart';
 import 'package:open_weather_client/open_weather.dart';
 
+/// A screen that demonstrates the use of prebuilt functions from the OpenWeather package.
 class PrebuiltFunctionScreen extends StatefulWidget {
+  /// Creates a [PrebuiltFunctionScreen].
   const PrebuiltFunctionScreen({super.key});
 
   @override
@@ -33,49 +37,55 @@ class _PrebuiltFunctionScreenState extends State<PrebuiltFunctionScreen> {
     // });
   }
 
-  // ignore: unused_element
+  /// Fetches the current weather data by city name.
+  ///
+  /// Returns a [WeatherData] object containing the current weather information.
   Future<WeatherData> _getCurrentweatherByCity() async {
-    return openWeather.currentWeatherByCityName(
-        cityName: _cityName, weatherUnits: WeatherUnits.METRIC);
+    return openWeather.currentWeatherByCityName(cityName: _cityName, weatherUnits: WeatherUnits.METRIC);
   }
 
-  // ignore: unused_element
+  /// Fetches the current weather data by geographic location.
+  ///
+  /// Returns a [WeatherData] object containing the current weather information.
   Future<WeatherData> _getCurrentweatherByLocation() async {
     return openWeather.currentWeatherByLocation(
-        latitude: _latitude,
-        longitude: _longitude,
-        weatherUnits: WeatherUnits.METRIC);
+        latitude: _latitude, longitude: _longitude, weatherUnits: WeatherUnits.METRIC);
   }
 
+  /// Fetches the current weather data by zip code.
+  ///
+  /// Returns a [WeatherData] object containing the current weather information.
   Future<WeatherData> _getCurrentweatherByZipCode() async {
     return openWeather.currentWeatherByZipCode(
-        zipCode: _zipCode,
-        countryCode: _countryCode,
-        weatherUnits: WeatherUnits.METRIC);
+        zipCode: _zipCode, countryCode: _countryCode, weatherUnits: WeatherUnits.METRIC);
   }
 
-  // ignore: unused_element
+  /// Fetches the five-day weather forecast by city name.
+  ///
+  /// Returns a [WeatherForecastData] object containing the weather forecast information.
   Future<WeatherForecastData> _getFiveDaysForecastByCityName() async {
-    return openWeather.fiveDaysWeatherForecastByCityName(
-        cityName: _cityName, weatherUnits: WeatherUnits.METRIC);
+    return openWeather.fiveDaysWeatherForecastByCityName(cityName: _cityName, weatherUnits: WeatherUnits.METRIC);
   }
 
-  // ignore: unused_element
+  /// Fetches the five-day weather forecast by geographic location.
+  ///
+  /// Returns a [WeatherForecastData] object containing the weather forecast information.
   Future<WeatherForecastData> _getFiveDaysForecastByLocation() async {
     return openWeather.fiveDaysWeatherForecastByLocation(
-        latitude: _latitude,
-        longitude: _longitude,
-        weatherUnits: WeatherUnits.METRIC);
+        latitude: _latitude, longitude: _longitude, weatherUnits: WeatherUnits.METRIC);
   }
 
-  // ignore: unused_element
+  /// Fetches the five-day weather forecast by zip code.
+  ///
+  /// Returns a [WeatherForecastData] object containing the weather forecast information.
   Future<WeatherForecastData> _getFiveDaysForecastByZipCode() async {
     return openWeather.fiveDaysWeatherForecastByZipCode(
-        zipCode: _zipCode,
-        countryCode: _countryCode,
-        weatherUnits: WeatherUnits.METRIC);
+        zipCode: _zipCode, countryCode: _countryCode, weatherUnits: WeatherUnits.METRIC);
   }
 
+  /// Builds a button that navigates back to the previous screen.
+  ///
+  /// Returns an [ElevatedButton] widget.
   Widget _buildButton() {
     return ElevatedButton(
       child: const Text('Check with prebuilt widgets'),
@@ -93,9 +103,7 @@ class _PrebuiltFunctionScreenState extends State<PrebuiltFunctionScreen> {
         backgroundColor: Colors.white,
         elevation: 0,
         title: const Text('OpenWeather prebuilt functions',
-            style: TextStyle(color: Colors.black),
-            maxLines: 2,
-            textAlign: TextAlign.center),
+            style: TextStyle(color: Colors.black), maxLines: 2, textAlign: TextAlign.center),
       ),
       body: Container(
           width: double.infinity,
@@ -113,19 +121,12 @@ class _PrebuiltFunctionScreenState extends State<PrebuiltFunctionScreen> {
                       ),
                       WeatherSummary(
                         color: Colors.black,
-                        imageUrl:
-                            'https://openweathermap.org/img/wn/${snapshot.data!.details.first.icon}@2x.png',
-                        currentTemperature: snapshot
-                            .data!.temperature.currentTemperature
-                            .toString(),
-                        maxTemperature:
-                            snapshot.data!.temperature.tempMax.toString(),
-                        minTemperature:
-                            snapshot.data!.temperature.tempMin.toString(),
-                        humidity:
-                            snapshot.data!.temperature.humidity.toString(),
-                        pressure:
-                            snapshot.data!.temperature.pressure.toString(),
+                        imageUrl: 'https://openweathermap.org/img/wn/${snapshot.data!.details.first.icon}@2x.png',
+                        currentTemperature: snapshot.data!.temperature.currentTemperature.toString(),
+                        maxTemperature: snapshot.data!.temperature.tempMax.toString(),
+                        minTemperature: snapshot.data!.temperature.tempMin.toString(),
+                        humidity: snapshot.data!.temperature.humidity.toString(),
+                        pressure: snapshot.data!.temperature.pressure.toString(),
                       ),
                       _buildButton()
                     ],

example/lib/screens/prebuilt_widgets_demo_screen.dart

@@ -3,27 +3,34 @@ import 'package:flutter/material.dart';
 import 'package:open_weather_client/enums/languages.dart';
 import 'package:open_weather_client/open_weather.dart';
 
+/// A screen that demonstrates the use of prebuilt widgets from the OpenWeather package.
 class PrebuiltWidgetsScreen extends StatefulWidget {
+  /// Creates a [PrebuiltWidgetsScreen].
   const PrebuiltWidgetsScreen({super.key});
 
   @override
   State<PrebuiltWidgetsScreen> createState() => _PrebuiltWidgetsScreenState();
 }
 
 class _PrebuiltWidgetsScreenState extends State<PrebuiltWidgetsScreen> {
+  /// The name of the city for which to display weather information.
   final String _cityName = 'Miami';
+
+  /// The API key for accessing the OpenWeather API.
   final String _key = 'c4bbb94f9fcfede0eb5219111804b040';
+
+  /// The latitude of the location for which to display weather information.
   final double _latitude = 52.3545828;
+
+  /// The longitude of the location for which to display weather information.
   final double _longitude = 4.7638781;
 
+  /// Builds a button that navigates to the [PrebuiltFunctionScreen].
   Widget _buildButton() {
     return ElevatedButton(
       child: const Text('Check with prebuilt functions'),
-      onPressed: () => Navigator.push(
-          context,
-          MaterialPageRoute(
-              builder: (BuildContext context) =>
-                  const PrebuiltFunctionScreen())),
+      onPressed: () =>
+          Navigator.push(context, MaterialPageRoute(builder: (BuildContext context) => const PrebuiltFunctionScreen())),
     );
   }