docs: clarify API usage details

Author: andrepimpao

README.md

@@ -9,8 +9,9 @@ air pollution, geocoding, maps, stations, and One Call. Responses use typed
 entities that safely handle conditional, missing, and `null` data.
 
 The library is built on
-[`programmatordev/php-api-sdk`](https://github.com/programmatordev/php-api-sdk)
-and supports client-wide and request-local configuration.
+[`programmatordev/php-api-sdk`](https://github.com/programmatordev/php-api-sdk),
+which provides HTTP client discovery and optional caching, logging, plugins,
+and request hooks.
 
 ## Requirements
 

docs/maps.md

@@ -106,12 +106,11 @@ For example:
 | 2 | 4 × 4 | 0–3 |
 | 6 | 64 × 64 | 0–63 |
 
-Zoom must be zero or greater. At any zoom level, the largest valid X or Y value
-is `(2 ** $zoom) - 1`. Mapping libraries normally calculate these indexes from
-the displayed geographic area; they should not be replaced directly with a
-location's longitude and latitude.
-
-Applications displaying Weather Maps data must provide visible OpenWeather
-attribution. Consult the
-[official FAQ](https://openweathermap.org/faq)
-for the current attribution requirements.
+Zoom must be zero or greater. X and Y start at 0, and their highest valid value
+is one less than the number of tiles along that axis, as shown in the table.
+Mapping libraries normally calculate these indexes from the displayed
+geographic area; they should not be replaced directly with a location's
+longitude and latitude.
+
+OpenWeather's attribution requirements depend on the applicable license. See
+the [official FAQ](https://openweathermap.org/faq) for current guidance.

docs/one-call.md

@@ -39,30 +39,6 @@ foreach ($current->conditions() as $condition) {
 }
 ```
 
-Configure units and language for a request:
-
-```php
-use ProgrammatorDev\OpenWeatherMap\Enum\Language;
-use ProgrammatorDev\OpenWeatherMap\Enum\Units;
-
-$current = $api
-    ->oneCall()
-    ->withUnits(Units::IMPERIAL)
-    ->withLanguage(Language::PORTUGUESE)
-    ->current(38.7223, -9.1393);
-```
-
-Measurement getters return nullable values. Related methods provide the unit
-and a formatted value. With the default metric configuration, for example:
-
-```php
-use ProgrammatorDev\OpenWeatherMap\Enum\Unit;
-
-$current->temperature();          // 24.34
-$current->temperatureUnit();      // Unit::CELSIUS
-$current->temperatureWithUnit();  // '24.34 °C'
-```
-
 ## Minute Timeline
 
 See OpenWeather's
@@ -241,7 +217,7 @@ these getters return nullable floats without conversion.
 
 ## Timeline Pagination
 
-The 15-minute, one-hour, and one-day timelines support pagination.
+The 15-minute, hour, and day timelines support pagination.
 
 ```php
 $timeline = $api->oneCall()->hourTimeline(
@@ -268,6 +244,34 @@ The availability checks and URL getters do not make another API request.
 is available and otherwise return `null`. The library does not fetch every page
 automatically. Each page navigation sends a separate API request.
 
+## Units And Language
+
+Current and timeline requests use the client configuration by default. Use
+`withUnits()` and `withLanguage()` to change those values for one request
+chain.
+
+```php
+use ProgrammatorDev\OpenWeatherMap\Enum\Language;
+use ProgrammatorDev\OpenWeatherMap\Enum\Units;
+
+$current = $api
+    ->oneCall()
+    ->withUnits(Units::IMPERIAL)
+    ->withLanguage(Language::PORTUGUESE)
+    ->current(38.7223, -9.1393);
+```
+
+Measurement getters return nullable values. Related methods provide the unit
+and a formatted value. With the default metric configuration, for example:
+
+```php
+use ProgrammatorDev\OpenWeatherMap\Enum\Unit;
+
+$current->temperature();          // 24.34
+$current->temperatureUnit();      // Unit::CELSIUS
+$current->temperatureWithUnit();  // '24.34 °C'
+```
+
 ## Alert
 
 See OpenWeather's

docs/setup.md

@@ -15,9 +15,9 @@ The examples below use objects supplied by the application:
 `$httpClient` implements PSR-18, `$cachePool` implements PSR-6, and `$logger`
 implements PSR-3.
 
-Setup changes apply to subsequent requests made by the client. They do not
-affect methods such as `maps()->tileUrl()` and `maps()->tileUrlTemplate()`,
-which generate URLs without making an HTTP request.
+Setup changes apply to later requests made by the client. Some methods do not
+send an HTTP request and are therefore unaffected. Their API guides note this
+where relevant.
 
 ## HTTP Client
 

docs/weather.md

@@ -36,9 +36,9 @@ echo $current->humidity();
 echo $current->visibility();
 ```
 
-`minimumTemperature()` and `maximumTemperature()` are the lowest and highest
-temperatures currently observed within the requested location. OpenWeather
-notes that they are mainly useful for geographically large cities; they are not
+`minimumTemperature()` and `maximumTemperature()` are OpenWeather's optional
+minimum and maximum temperatures for the city at the current moment. They are
+mainly useful for large cities and often match `temperature()`. They are not
 the day's forecast low and high.
 
 Conditions, wind, and clouds are exposed as nested entities. A condition keeps
@@ -78,8 +78,9 @@ See the
 [official forecast documentation](https://openweathermap.org/api/forecast5)
 for API details.
 
-Use `forecast()` with a latitude and longitude. The optional `count` limits the
-number of three-hour periods returned and must be positive.
+Use `forecast()` with a latitude and longitude to retrieve up to five days of
+weather forecasts, with one period every three hours. The optional `count`
+limits the number of periods returned and must be positive.
 
 ```php
 $forecast = $api->weather()->forecast(