Documentation

Follow Effective Dart: Documentation: start with a one-sentence summary, use [identifiers] for links, document parameters in prose, and provide examples. pub.dev renders docs for published packages.

/// A client for the Weather API.
///
/// Use [WeatherClient.forecast] to fetch a multi-day forecast:
///
/// ```dart
/// final client = WeatherClient(apiKey: 'xyz');
/// final days = await client.forecast('Pune', days: 3);
/// ```
///
/// Throws [WeatherException] if the request fails.
class WeatherClient {
  /// Creates a client authenticated with [apiKey].
  WeatherClient({required this.apiKey});

  /// The API key used for all requests.
  final String apiKey;

  /// Returns the forecast for [city] for the next [days] days.
  Future<List<Forecast>> forecast(String city, {int days = 1}) async => [];
}

dart doc .                     # generates doc/api (HTML)