chore: improved supported APIs page documentation

Author: andrepimpao

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 programmatordev
+Copyright (c) 2023 Programmator
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -62,7 +62,7 @@ echo $currentWeather->getTemperature();
 
 ## Contributing
 
-Any form of contribution to improve this library will be welcome and appreciated.
+Any form of contribution to improve this library (including requests) will be welcome and appreciated.
 Make sure to open a pull request or issue.
 
 ## License

docs/03-supported-apis.md

@@ -2,58 +2,70 @@
 
 - [APIs](#apis)
  - [One Call](#one-call)
- - [getWeather](#getweatherfloat-latitude-float-longitude)
- - [getHistoryMoment](#gethistorymomentfloat-latitude-float-longitude-datetimeinterface-datetime)
- - [getHistoryAggregate](#gethistoryaggregatefloat-latitude-float-longitude-datetimeinterface-date)
+ - [getWeather](#getweather)
+ - [getHistoryMoment](#gethistorymoment)
+ - [getHistoryAggregate](#gethistoryaggregate)
  - [Weather](#weather)
- - [getCurrent](#getcurrentfloat-latitude-float-longitude)
- - [getForecast](#getforecastfloat-latitude-float-longitude-int-numresults--40)
+ - [getCurrent](#getcurrent)
+ - [getForecast](#getforecast)
  - [Air Pollution](#air-pollution)
- - [getCurrent](#getcurrentfloat-latitude-float-longitude-1)
- - [getForecast](#getforecastfloat-latitude-float-longitude)
- - [getHistory](#gethistoryfloat-latitude-float-longitude-datetimeinterface-startdate-datetimeinterface-enddate)
+ - [getCurrent](#getcurrent-1)
+ - [getForecast](#getforecast-1)
+ - [getHistory](#gethistory)
  - [Geocoding](#geocoding)
- - [getByLocationName](#getbylocationnamestring-locationname-int-numresults--5)
- - [getByZipCode](#getbyzipcodestring-zipcode-string-countrycode)
- - [getByCoordinate](#getbycoordinatefloat-latitude-float-longitude-int-numresults--5)
+ - [getByLocationName](#getbylocationname)
+ - [getByZipCode](#getbyzipcode)
+ - [getByCoordinate](#getbycoordinate)
 - [Common Methods](#common-methods)
- - [withUnitSystem](#withunitsystemstring-unitsystem)
- - [withLanguage](#withlanguagestring-language)
- - [withCacheTtl](#withcachettlint-time)
+ - [withUnitSystem](#withunitsystem)
+ - [withLanguage](#withlanguage)
+ - [withCacheTtl](#withcachettl)
 
 ## APIs
 
 ### One Call
 
-#### `getWeather(float $latitude, float $longitude)`
+#### `getWeather`
+
+```php
+getWeather(float $latitude, float $longitude): OneCall
+```
 
 Get current and forecast (minutely, hourly and daily) weather data.
 
-Returns a [`OneCall`](05-objects.md#onecall) object.
+Returns a [`OneCall`](05-objects.md#onecall) object:
 
 ```php
 $weather = $openWeatherMap->getOneCall()->getWeather(50, 50);
 
 echo $weather->getCurrent()->getTemperature();
 ```
 
-#### `getHistoryMoment(float $latitude, float $longitude, \DateTimeInterface $dateTime)`
+#### `getHistoryMoment`
+
+```php
+getHistoryMoment(float $latitude, float $longitude, \DateTimeInterface $dateTime): WeatherLocation
+```
 
 Get weather data from a single moment in the past.
 
-Returns a [`WeatherLocation`](05-objects.md#weatherlocation) object.
+Returns a [`WeatherLocation`](05-objects.md#weatherlocation) object:
 
 ```php
 $weather = $openWeatherMap->getOneCall()->getHistoryMoment(50, 50, new \DateTime('2023-01-01 12:00:00'));
 
 echo $weather->getTemperature();
 ```
 
-#### `getHistoryAggregate(float $latitude, float $longitude, \DateTimeInterface $date)`
+#### `getHistoryAggregate`
+
+```php
+getHistoryAggregate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherAggregate
+```
 
 Get aggregated weather data from a single day in the past.
 
-Returns a [`WeatherAggregate`](05-objects.md#weatheraggregate) object.
+Returns a [`WeatherAggregate`](05-objects.md#weatheraggregate) object:
 
 ```php
 $weather = $openWeatherMap->getOneCall()->getHistoryAggregate(50, 50, new \DateTime('1985-07-19'));
@@ -63,23 +75,31 @@ echo $weather->getTemperature();
 
 ### Weather
 
-#### `getCurrent(float $latitude, float $longitude)`
+#### `getCurrent`
+
+```php
+getCurrent(float $latitude, float $longitude): WeatherLocation
+```
 
 Get current weather data.
 
-Returns a [`WeatherLocation`](05-objects.md#weatherlocation-1) object.
+Returns a [`WeatherLocation`](05-objects.md#weatherlocation-1) object:
 
 ```php
 $weather = $openWeatherMap->getWeather()->getCurrent(50, 50);
 
 echo $weather->getTemperature();
 ```
 
-#### `getForecast(float $latitude, float $longitude, int $numResults = 40)`
+#### `getForecast`
+
+```php
+getForecast(float $latitude, float $longitude, int $numResults = 40): WeatherLocationList
+```
 
 Get weather forecast data per 3-hour steps for the next 5 days.
 
-Returns a [`WeatherLocationList`](05-objects.md#weatherlocationlist) object.
+Returns a [`WeatherLocationList`](05-objects.md#weatherlocationlist) object:
 
 ```php
 // Since it returns 3-hour steps,
@@ -94,11 +114,15 @@ foreach ($weatherForecast->getList() as $weather) {
 
 ### Air Pollution
 
-#### `getCurrent(float $latitude, float $longitude)`
+#### `getCurrent`
+
+```php
+getCurrent(float $latitude, float $longitude): AirPollutionLocation
+```
 
 Get current air pollution data.
 
-Returns a [`AirPollutionLocation`](05-objects.md#airpollutionlocation) object.
+Returns a [`AirPollutionLocation`](05-objects.md#airpollutionlocation) object:
 
 ```php
 $airPollution = $openWeatherMap->getAirPollution()->getCurrent(50, 50);
@@ -107,11 +131,15 @@ echo $airPollution->getAirQuality()->getQualitativeName();
 echo $airPollution->getCarbonMonoxide();
 ```
 
-#### `getForecast(float $latitude, float $longitude)`
+#### `getForecast`
+
+```php
+getForecast(float $latitude, float $longitude): AirPollutionLocationList
+```
 
 Get air pollution forecast data per 1-hour for the next 24 hours.
 
-Returns a [`AirPollutionLocationList`](05-objects.md#airpollutionlocationlist) object.
+Returns a [`AirPollutionLocationList`](05-objects.md#airpollutionlocationlist) object:
 
 ```php
 $airPollutionForecast = $openWeatherMap->getAirPollution()->getForecast(50, 50);
@@ -123,11 +151,15 @@ foreach ($airPollutionForecast->getList() as $airPollution) {
 }
 ```
 
-#### `getHistory(float $latitude, float $longitude, \DateTimeInterface $startDate, \DateTimeInterface $endDate)`
+#### `getHistory`
+
+```php
+getHistory(float $latitude, float $longitude, \DateTimeInterface $startDate, \DateTimeInterface $endDate): AirPollutionLocationList
+```
 
 Get air pollution history data between two dates.
 
-Returns a [`AirPollutionLocationList`](05-objects.md#airpollutionlocationlist) object.
+Returns a [`AirPollutionLocationList`](05-objects.md#airpollutionlocationlist) object:
 
 ```php
 $startDate = new \DateTime('-7 days'); // 7 days ago
@@ -143,11 +175,18 @@ foreach ($airPollutionHistory->getList() as $airPollution) {
 
 ### Geocoding
 
-#### `getByLocationName(string $locationName, int $numResults = 5)`
+#### `getByLocationName`
+
+```php
+/**
+ * @return Location[]
+ */
+getByLocationName(string $locationName, int $numResults = 5): array
+```
 
 Get locations data by location name.
 
-Returns an array of [`Location`](05-objects.md#location) objects.
+Returns an array of [`Location`](05-objects.md#location) objects:
 
 ```php
 $locations = $openWeatherMap->getGeocoding()->getByLocationName('lisbon');
@@ -158,23 +197,34 @@ foreach ($locations as $location) {
 }
 ```
 
-#### `getByZipCode(string $zipCode, string $countryCode)`
+#### `getByZipCode`
+
+```php
+getByZipCode(string $zipCode, string $countryCode): ZipCodeLocation
+```
 
 Get location data by zip/post code.
 
-Returns a [`ZipCodeLocation`](05-objects.md#zipcodelocation) object.
+Returns a [`ZipCodeLocation`](05-objects.md#zipcodelocation) object:
 
 ```php
 $location = $openWeatherMap->getGeocoding()->getByZipCode('1000-001', 'pt');
 
 echo $location->getName();
 ```
 
-#### `getByCoordinate(float $latitude, float $longitude, int $numResults = 5)`
+#### `getByCoordinate`
+
+```php
+/**
+ * @return Location[]
+ */
+getByCoordinate(float $latitude, float $longitude, int $numResults = 5): array
+```
 
 Get locations data by coordinate.
 
-Returns an array of [`Location`](05-objects.md#location) objects.
+Returns an array of [`Location`](05-objects.md#location) objects:
 
 ```php
 $locations = $openWeatherMap->getGeocoding()->getByCoordinate(50, 50);
@@ -187,7 +237,11 @@ foreach ($locations as $location) {
 
 ## Common Methods
 
-#### `withUnitSystem(string $unitSystem)`
+#### `withUnitSystem`
+
+```php
+withUnitSystem(string $unitSystem): self
+```
 
 Makes a request with a different unit system from the one globally defined in the [configuration](02-configuration.md#unitsystem).
 
@@ -202,7 +256,11 @@ $openWeatherMap->getWeather()
  ->getCurrent(50, 50);
 ```
 
-#### `withLanguage(string $language)`
+#### `withLanguage`
+
+```php
+withLanguage(string $language): self
+```
 
 Makes a request with a different language from the one globally defined in the [configuration](02-configuration.md#language).
 
@@ -217,7 +275,11 @@ $openWeatherMap->getWeather()
  ->getCurrent(50, 50);
 ```
 
-#### `withCacheTtl(?int $time)`
+#### `withCacheTtl`
+
+```php
+withCacheTtl(?int $time): self
+```
 
 Makes a request and saves into cache with the provided time duration value (in seconds). 
 Check the [Cache TTL](02-configuration.md#cache-ttl) section for more information regarding default values.