chore: document public APIs (part 1)

analysis_options.yaml

@@ -42,3 +42,5 @@ linter:
     use_if_null_to_convert_nulls_to_bools: true
     matching_super_parameters: true
     prefer_const_constructors: true
+    # TODO: enable the following lint when all public APIs are documented
+    # public_member_api_docs: true

example/analysis_options.yaml

@@ -6,3 +6,5 @@ linter:
   rules:
     # using the default parameter values are used as explanation and for showcase
     avoid_redundant_argument_values: false
+    # don't enforce documentation for the example app
+    public_member_api_docs: false

lib/src/geo/crs.dart

@@ -13,15 +13,19 @@ import 'package:proj4dart/proj4dart.dart' as proj4;
 /// points of objects of different dimensions. In our case 3D and 2D objects.
 @immutable
 abstract class Crs {
+  /// The code
   @nonVirtual
   final String code;
+
+  /// Set to true if the CRS has no bounds.
   @nonVirtual
   final bool infinite;
   @nonVirtual
   final (double, double)? wrapLng;
   @nonVirtual
   final (double, double)? wrapLat;
 
+  /// Constant base constructor that sets all values for the abstract [Crs].
   const Crs({
     required this.code,
     required this.infinite,
@@ -40,6 +44,7 @@ abstract class Crs {
   /// scaled map point.
   (double, double) latLngToXY(LatLng latlng, double scale);
 
+  /// Similar to [latLngToXY] but converts the XY coordinates to a [Point].
   Point<double> latLngToPoint(LatLng latlng, double zoom) {
     final (x, y) = latLngToXY(latlng, scale(zoom));
     return Point<double>(x, y);
@@ -116,7 +121,7 @@ abstract class CrsWithStaticTransformation extends Crs {
   }
 }
 
-// Custom CRS for non geographical maps
+/// Custom CRS for non geographical maps
 @immutable
 class CrsSimple extends CrsWithStaticTransformation {
   const CrsSimple()
@@ -130,11 +135,12 @@ class CrsSimple extends CrsWithStaticTransformation {
         );
 }
 
-/// The most common CRS used for rendering maps.
+/// EPSG:3857, The most common CRS used for rendering maps.
 @immutable
 class Epsg3857 extends CrsWithStaticTransformation {
   static const double _scale = 0.5 / (math.pi * SphericalMercator.r);
 
+  /// Create a new [Epsg3857] object.
   const Epsg3857()
       : super._(
           code: 'EPSG:3857',
@@ -163,9 +169,11 @@ class Epsg3857 extends CrsWithStaticTransformation {
   }
 }
 
-/// A common CRS among GIS enthusiasts. Uses simple Equirectangular projection.
+/// EPSG:4326, A common CRS among GIS enthusiasts.
+/// Uses simple Equirectangular projection.
 @immutable
 class Epsg4326 extends CrsWithStaticTransformation {
+  /// Create a new [Epsg4326] CRS instance.
   const Epsg4326()
       : super._(
           projection: const _LonLat(),
@@ -341,18 +349,26 @@ class Proj4Crs extends Crs {
   }
 }
 
+/// The abstract base [Projection] class, used for coordinate reference
+/// systems like [Epsg3857].
+/// Inherit from this class if you want to create or implement your own CRS.
 @immutable
 abstract class Projection {
+  /// The [Bounds] for the coordinates of this [Projection].
   final Bounds<double>? bounds;
 
+  /// Base constructor for the abstract [Projection] class that sets the
+  /// required fields.
   const Projection(this.bounds);
 
+  /// Converts a [LatLng] to a coordinates and returns them as [Point] object.
   @nonVirtual
   Point<double> project(LatLng latlng) {
     final (x, y) = projectXY(latlng);
     return Point<double>(x, y);
   }
 
+  /// Converts a [LatLng] to geometry coordinates.
   (double, double) projectXY(LatLng latlng);
 
   @nonVirtual
@@ -381,15 +397,21 @@ class _LonLat extends Projection {
 
 @immutable
 class SphericalMercator extends Projection {
+  /// The radius
   static const int r = 6378137;
+
+  /// The maximum latitude
   static const double maxLatitude = 85.0511287798;
+
   static const double _boundsD = r * math.pi;
 
+  /// The constant Bounds of the [SphericalMercator] projection.
   static const Bounds<double> _bounds = Bounds<double>.unsafe(
     Point<double>(-_boundsD, -_boundsD),
     Point<double>(_boundsD, _boundsD),
   );
 
+  /// Constant constructor for the [SphericalMercator] projection.
   const SphericalMercator() : super(_bounds);
 
   static double projectLat(double latitude) {

lib/src/geo/latlng_bounds.dart

@@ -9,11 +9,16 @@ class LatLngBounds {
   late LatLng _sw;
   late LatLng _ne;
 
+  /// Create new [LatLngBounds] by providing two corners. Both corners have to
+  /// be on opposite sites but it doesn't matter which opposite corners or in
+  /// what order the corners are provided.
   LatLngBounds(
     LatLng corner1,
     LatLng corner2,
   ) : this.fromPoints([corner1, corner2]);
 
+  /// Create a new [LatLngBounds] from a list of [LatLng] points. This
+  /// calculates the bounding box of the provided points.
   LatLngBounds.fromPoints(List<LatLng> points)
       : assert(
           points.isNotEmpty,

lib/src/gestures/interactive_flag.dart

@@ -14,6 +14,8 @@
 abstract class InteractiveFlag {
   const InteractiveFlag._();
 
+  /// All available interactive flags, use as `flags: InteractiveFlag.all` to
+  /// enable all gestures.
   static const int all = drag |
       flingAnimation |
       pinchMove |

lib/src/gestures/latlng_tween.dart

@@ -1,7 +1,12 @@
 import 'package:flutter/animation.dart';
+import 'package:flutter_map/flutter_map.dart';
 import 'package:latlong2/latlong.dart';
 
+/// A [Tween] object for [LatLng]. Used for [AnimationController] to handle
+/// animated changes of the [MapCamera].
 class LatLngTween extends Tween<LatLng> {
+  /// Create a new [LatLngBounds] object by providing the [begin] and [end]
+  /// coordinates.
   LatLngTween({required LatLng begin, required LatLng end})
       : super(begin: begin, end: end);